{ "openapi": "3.0.3", "info": { "title": "goose-server", "description": "An AI agent", "contact": { "name": "Block", "email": "ai-oss-tools@block.xyz" }, "license": { "name": "Apache-2.0" }, "version": "1.0.17" }, "paths": { "/agent/tools": { "get": { "tags": [ "super::routes::agent" ], "operationId": "get_tools", "parameters": [ { "name": "extension_name", "in": "query", "description": "Optional extension name to filter tools", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Tools retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } }, "401": { "description": "Unauthorized - invalid secret key" }, "424": { "description": "Agent not initialized" }, "500": { "description": "Internal server error" } } } }, "/config": { "get": { "tags": [ "super::routes::config_management" ], "operationId": "read_all_config", "responses": { "200": { "description": "All configuration values retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigResponse" } } } } } } }, "/config/extensions": { "get": { "tags": [ "super::routes::config_management" ], "operationId": "get_extensions", "responses": { "200": { "description": "All extensions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionResponse" } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "super::routes::config_management" ], "operationId": "add_extension", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionQuery" } } }, "required": true }, "responses": { "200": { "description": "Extension added or updated successfully", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request" }, "422": { "description": "Could not serialize config.yaml" }, "500": { "description": "Internal server error" } } } }, "/config/extensions/{name}": { "delete": { "tags": [ "super::routes::config_management" ], "operationId": "remove_extension", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Extension removed successfully", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Extension not found" }, "500": { "description": "Internal server error" } } } }, "/config/init": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "init_config", "responses": { "200": { "description": "Config initialization check completed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Internal server error" } } } }, "/config/providers": { "get": { "tags": [ "super::routes::config_management" ], "operationId": "providers", "responses": { "200": { "description": "All configuration values retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderDetails" } } } } } } } }, "/config/read": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "read_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigKeyQuery" } } }, "required": true }, "responses": { "200": { "description": "Configuration value retrieved successfully", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Configuration key not found" } } } }, "/config/remove": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "remove_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigKeyQuery" } } }, "required": true }, "responses": { "200": { "description": "Configuration value removed successfully", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Configuration key not found" }, "500": { "description": "Internal server error" } } } }, "/config/upsert": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "upsert_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertConfigQuery" } } }, "required": true }, "responses": { "200": { "description": "Configuration value upserted successfully", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Internal server error" } } } } }, "components": { "schemas": { "ConfigKey": { "type": "object", "required": [ "name", "required", "secret" ], "properties": { "default": { "type": "string", "nullable": true }, "name": { "type": "string" }, "required": { "type": "boolean" }, "secret": { "type": "boolean" } } }, "ConfigKeyQuery": { "type": "object", "required": [ "key", "is_secret" ], "properties": { "is_secret": { "type": "boolean" }, "key": { "type": "string" } } }, "ConfigResponse": { "type": "object", "required": [ "config" ], "properties": { "config": { "type": "object", "additionalProperties": {} } } }, "Envs": { "type": "object", "additionalProperties": { "type": "string", "description": "A map of environment variables to set, e.g. API_KEY -> some_secret, HOST -> host" } }, "ExtensionConfig": { "oneOf": [ { "type": "object", "description": "Server-sent events client with a URI endpoint", "required": [ "name", "uri", "type" ], "properties": { "bundled": { "type": "boolean", "description": "Whether this extension is bundled with Goose", "nullable": true }, "description": { "type": "string", "nullable": true }, "envs": { "$ref": "#/components/schemas/Envs" }, "name": { "type": "string", "description": "The name used to identify this extension" }, "timeout": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "type": { "type": "string", "enum": [ "sse" ] }, "uri": { "type": "string" } } }, { "type": "object", "description": "Standard I/O client with command and arguments", "required": [ "name", "cmd", "args", "type" ], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "bundled": { "type": "boolean", "description": "Whether this extension is bundled with Goose", "nullable": true }, "cmd": { "type": "string" }, "description": { "type": "string", "nullable": true }, "envs": { "$ref": "#/components/schemas/Envs" }, "name": { "type": "string", "description": "The name used to identify this extension" }, "timeout": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "type": { "type": "string", "enum": [ "stdio" ] } } }, { "type": "object", "description": "Built-in extension that is part of the goose binary", "required": [ "name", "type" ], "properties": { "bundled": { "type": "boolean", "description": "Whether this extension is bundled with Goose", "nullable": true }, "display_name": { "type": "string", "nullable": true }, "name": { "type": "string", "description": "The name used to identify this extension" }, "timeout": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "type": { "type": "string", "enum": [ "builtin" ] } } }, { "type": "object", "description": "Frontend-provided tools that will be called through the frontend", "required": [ "name", "tools", "type" ], "properties": { "bundled": { "type": "boolean", "description": "Whether this extension is bundled with Goose", "nullable": true }, "instructions": { "type": "string", "description": "Instructions for how to use these tools", "nullable": true }, "name": { "type": "string", "description": "The name used to identify this extension" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" }, "description": "The tools provided by the frontend" }, "type": { "type": "string", "enum": [ "frontend" ] } } } ], "description": "Represents the different types of MCP extensions that can be added to the manager", "discriminator": { "propertyName": "type" } }, "ExtensionEntry": { "allOf": [ { "$ref": "#/components/schemas/ExtensionConfig" }, { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } ] }, "ExtensionQuery": { "type": "object", "required": [ "name", "config", "enabled" ], "properties": { "config": { "$ref": "#/components/schemas/ExtensionConfig" }, "enabled": { "type": "boolean" }, "name": { "type": "string" } } }, "ExtensionResponse": { "type": "object", "required": [ "extensions" ], "properties": { "extensions": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionEntry" } } } }, "PermissionLevel": { "type": "string", "description": "Enum representing the possible permission levels for a tool.", "enum": [ "always_allow", "ask_before", "never_allow" ] }, "ProviderDetails": { "type": "object", "required": [ "name", "metadata", "is_configured" ], "properties": { "is_configured": { "type": "boolean", "description": "Indicates whether the provider is fully configured" }, "metadata": { "$ref": "#/components/schemas/ProviderMetadata" }, "name": { "type": "string", "description": "Unique identifier and name of the provider" } } }, "ProviderMetadata": { "type": "object", "description": "Metadata about a provider's configuration requirements and capabilities", "required": [ "name", "display_name", "description", "default_model", "known_models", "model_doc_link", "config_keys" ], "properties": { "config_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigKey" }, "description": "Required configuration keys" }, "default_model": { "type": "string", "description": "The default/recommended model for this provider" }, "description": { "type": "string", "description": "Description of the provider's capabilities" }, "display_name": { "type": "string", "description": "Display name for the provider in UIs" }, "known_models": { "type": "array", "items": { "type": "string" }, "description": "A list of currently known models\nTODO: eventually query the apis directly" }, "model_doc_link": { "type": "string", "description": "Link to the docs where models can be found" }, "name": { "type": "string", "description": "The unique identifier for this provider" } } }, "ProvidersResponse": { "type": "object", "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderDetails" } } } }, "Tool": { "type": "object", "description": "A tool that can be used by a model.", "required": [ "name", "description", "inputSchema" ], "properties": { "annotations": { "allOf": [ { "$ref": "#/components/schemas/ToolAnnotations" } ], "nullable": true }, "description": { "type": "string", "description": "A description of what the tool does" }, "inputSchema": { "description": "A JSON Schema object defining the expected parameters for the tool" }, "name": { "type": "string", "description": "The name of the tool" } } }, "ToolAnnotations": { "type": "object", "description": "Additional properties describing a tool to clients.\n\nNOTE: all properties in ToolAnnotations are **hints**.\nThey are not guaranteed to provide a faithful description of\ntool behavior (including descriptive properties like `title`).\n\nClients should never make tool use decisions based on ToolAnnotations\nreceived from untrusted servers.", "properties": { "destructiveHint": { "type": "boolean", "description": "If true, the tool may perform destructive updates to its environment.\nIf false, the tool performs only additive updates.\n\n(This property is meaningful only when `read_only_hint == false`)\n\nDefault: true" }, "idempotentHint": { "type": "boolean", "description": "If true, calling the tool repeatedly with the same arguments\nwill have no additional effect on its environment.\n\n(This property is meaningful only when `read_only_hint == false`)\n\nDefault: false" }, "openWorldHint": { "type": "boolean", "description": "If true, this tool may interact with an \"open world\" of external\nentities. If false, the tool's domain of interaction is closed.\nFor example, the world of a web search tool is open, whereas that\nof a memory tool is not.\n\nDefault: true" }, "readOnlyHint": { "type": "boolean", "description": "If true, the tool does not modify its environment.\n\nDefault: false" }, "title": { "type": "string", "description": "A human-readable title for the tool.", "nullable": true } } }, "ToolInfo": { "type": "object", "description": "Information about the tool used for building prompts", "required": [ "name", "description", "parameters" ], "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "parameters": { "type": "array", "items": { "type": "string" } }, "permission": { "allOf": [ { "$ref": "#/components/schemas/PermissionLevel" } ], "nullable": true } } }, "UpsertConfigQuery": { "type": "object", "required": [ "key", "value", "is_secret" ], "properties": { "is_secret": { "type": "boolean" }, "key": { "type": "string" }, "value": {} } } } } }