{ "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.1.0" }, "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/ToolInfo" } } } } }, "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/backup": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "backup_config", "responses": { "200": { "description": "Config file backed up", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Internal server error" } } } }, "/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/permissions": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "upsert_permissions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPermissionsQuery" } } }, "required": true }, "responses": { "200": { "description": "Permission update completed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request" } } } }, "/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/recover": { "post": { "tags": [ "super::routes::config_management" ], "operationId": "recover_config", "responses": { "200": { "description": "Config recovery attempted", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Internal server error" } } } }, "/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" } } } }, "/config/validate": { "get": { "tags": [ "super::routes::config_management" ], "operationId": "validate_config", "responses": { "200": { "description": "Config validation result", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "Config file is corrupted" } } } }, "/confirm": { "post": { "tags": [ "super::routes::reply" ], "operationId": "confirm_permission", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionConfirmationRequest" } } }, "required": true }, "responses": { "200": { "description": "Permission action is confirmed", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Unauthorized - invalid secret key" }, "500": { "description": "Internal server error" } } } }, "/context/manage": { "post": { "tags": [ "Context Management" ], "operationId": "manage_context", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextManageRequest" } } }, "required": true }, "responses": { "200": { "description": "Context managed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextManageResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "412": { "description": "Precondition failed - Agent not available" }, "500": { "description": "Internal server error" } }, "security": [ { "api_key": [] } ] } }, "/recipes/create": { "post": { "tags": [ "Recipe Management" ], "summary": "Create a Recipe configuration from the current session", "operationId": "create_recipe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipeRequest" } } }, "required": true }, "responses": { "200": { "description": "Recipe created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipeResponse" } } } }, "400": { "description": "Bad request" }, "412": { "description": "Precondition failed - Agent not available" }, "500": { "description": "Internal server error" } } } }, "/recipes/decode": { "post": { "tags": [ "Recipe Management" ], "operationId": "decode_recipe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecodeRecipeRequest" } } }, "required": true }, "responses": { "200": { "description": "Recipe decoded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecodeRecipeResponse" } } } }, "400": { "description": "Bad request" } } } }, "/recipes/encode": { "post": { "tags": [ "Recipe Management" ], "operationId": "encode_recipe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncodeRecipeRequest" } } }, "required": true }, "responses": { "200": { "description": "Recipe encoded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncodeRecipeResponse" } } } }, "400": { "description": "Bad request" } } } }, "/schedule/create": { "post": { "tags": [ "schedule" ], "operationId": "create_schedule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Scheduled job created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledJob" } } } }, "400": { "description": "Invalid cron expression or recipe file" }, "409": { "description": "Job ID already exists" }, "500": { "description": "Internal server error" } } } }, "/schedule/delete/{id}": { "delete": { "tags": [ "schedule" ], "operationId": "delete_schedule", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Scheduled job deleted successfully" }, "404": { "description": "Scheduled job not found" }, "500": { "description": "Internal server error" } } } }, "/schedule/list": { "get": { "tags": [ "schedule" ], "operationId": "list_schedules", "responses": { "200": { "description": "A list of scheduled jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSchedulesResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/schedule/{id}": { "put": { "tags": [ "schedule" ], "operationId": "update_schedule", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Scheduled job updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledJob" } } } }, "400": { "description": "Cannot update a currently running job or invalid request" }, "404": { "description": "Scheduled job not found" }, "500": { "description": "Internal server error" } } } }, "/schedule/{id}/inspect": { "get": { "tags": [ "schedule" ], "operationId": "inspect_running_job", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule to inspect", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Running job information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectJobResponse" } } } }, "404": { "description": "Scheduled job not found" }, "500": { "description": "Internal server error" } } } }, "/schedule/{id}/kill": { "post": { "tags": [ "schedule" ], "operationId": "kill_running_job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Running job killed successfully" } } } }, "/schedule/{id}/pause": { "post": { "tags": [ "schedule" ], "operationId": "pause_schedule", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule to pause", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Scheduled job paused successfully" }, "400": { "description": "Cannot pause a currently running job" }, "404": { "description": "Scheduled job not found" }, "500": { "description": "Internal server error" } } } }, "/schedule/{id}/run_now": { "post": { "tags": [ "schedule" ], "operationId": "run_now_handler", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule to run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled job triggered successfully, returns new session ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunNowResponse" } } } }, "404": { "description": "Scheduled job not found" }, "500": { "description": "Internal server error when trying to run the job" } } } }, "/schedule/{id}/sessions": { "get": { "tags": [ "schedule" ], "operationId": "sessions_handler", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A list of session display info", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionDisplayInfo" } } } } }, "500": { "description": "Internal server error" } } } }, "/schedule/{id}/unpause": { "post": { "tags": [ "schedule" ], "operationId": "unpause_schedule", "parameters": [ { "name": "id", "in": "path", "description": "ID of the schedule to unpause", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Scheduled job unpaused successfully" }, "404": { "description": "Scheduled job not found" }, "500": { "description": "Internal server error" } } } }, "/sessions": { "get": { "tags": [ "Session Management" ], "operationId": "list_sessions", "responses": { "200": { "description": "List of available sessions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "500": { "description": "Internal server error" } }, "security": [ { "api_key": [] } ] } }, "/sessions/{session_id}": { "get": { "tags": [ "Session Management" ], "operationId": "get_session_history", "parameters": [ { "name": "session_id", "in": "path", "description": "Unique identifier for the session", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHistoryResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } }, "security": [ { "api_key": [] } ] } } }, "components": { "schemas": { "Annotations": { "type": "object", "properties": { "audience": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "priority": { "type": "number" }, "timestamp": { "type": "string", "format": "date-time" } } }, "Author": { "type": "object", "properties": { "contact": { "type": "string", "nullable": true }, "metadata": { "type": "string", "nullable": true } } }, "AuthorRequest": { "type": "object", "properties": { "contact": { "type": "string", "nullable": true }, "metadata": { "type": "string", "nullable": true } } }, "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": {} } } }, "Content": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string" } } }, { "type": "object", "required": [ "data", "mimeType", "type" ], "properties": { "data": { "type": "string" }, "mimeType": { "type": "string" }, "type": { "type": "string" } } }, { "type": "object", "required": [ "resource", "type" ], "properties": { "resource": { "$ref": "#/components/schemas/ResourceContents" }, "type": { "type": "string" } } }, { "type": "object", "required": [ "data", "mimeType", "type" ], "properties": { "annotations": { "allOf": [ { "$ref": "#/components/schemas/Annotations" } ] }, "data": { "type": "string" }, "mimeType": { "type": "string" }, "type": { "type": "string" } } } ] }, "ContextLengthExceeded": { "type": "object", "required": [ "msg" ], "properties": { "msg": { "type": "string" } } }, "ContextManageRequest": { "type": "object", "description": "Request payload for context management operations", "required": [ "messages", "manageAction" ], "properties": { "manageAction": { "type": "string", "description": "Operation to perform: \"truncation\" or \"summarize\"" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Collection of messages to be managed" } } }, "ContextManageResponse": { "type": "object", "description": "Response from context management operations", "required": [ "messages", "tokenCounts" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Processed messages after the operation" }, "tokenCounts": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Token counts for each processed message" } } }, "CreateRecipeRequest": { "type": "object", "required": [ "messages", "title", "description" ], "properties": { "activities": { "type": "array", "items": { "type": "string" }, "nullable": true }, "author": { "allOf": [ { "$ref": "#/components/schemas/AuthorRequest" } ], "nullable": true }, "description": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "title": { "type": "string" } } }, "CreateRecipeResponse": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "recipe": { "allOf": [ { "$ref": "#/components/schemas/Recipe" } ], "nullable": true } } }, "CreateScheduleRequest": { "type": "object", "required": [ "id", "recipe_source", "cron" ], "properties": { "cron": { "type": "string" }, "execution_mode": { "type": "string", "nullable": true }, "id": { "type": "string" }, "recipe_source": { "type": "string" } } }, "DecodeRecipeRequest": { "type": "object", "required": [ "deeplink" ], "properties": { "deeplink": { "type": "string" } } }, "DecodeRecipeResponse": { "type": "object", "required": [ "recipe" ], "properties": { "recipe": { "$ref": "#/components/schemas/Recipe" } } }, "EmbeddedResource": { "type": "object", "required": [ "resource" ], "properties": { "annotations": { "allOf": [ { "$ref": "#/components/schemas/Annotations" } ] }, "resource": { "$ref": "#/components/schemas/ResourceContents" } } }, "EncodeRecipeRequest": { "type": "object", "required": [ "recipe" ], "properties": { "recipe": { "$ref": "#/components/schemas/Recipe" } } }, "EncodeRecipeResponse": { "type": "object", "required": [ "deeplink" ], "properties": { "deeplink": { "type": "string" } } }, "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 }, "env_keys": { "type": "array", "items": { "type": "string" } }, "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 }, "env_keys": { "type": "array", "items": { "type": "string" } }, "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": "Streamable HTTP client with a URI endpoint using MCP Streamable HTTP specification", "required": [ "name", "uri", "type" ], "properties": { "bundled": { "type": "boolean", "description": "Whether this extension is bundled with Goose", "nullable": true }, "description": { "type": "string", "nullable": true }, "env_keys": { "type": "array", "items": { "type": "string" } }, "envs": { "$ref": "#/components/schemas/Envs" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string", "description": "The name used to identify this extension" }, "timeout": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "type": { "type": "string", "enum": [ "streamable_http" ] }, "uri": { "type": "string" } } }, { "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" } } } }, "FrontendToolRequest": { "type": "object", "required": [ "id", "toolCall" ], "properties": { "id": { "type": "string" }, "toolCall": { "type": "object" } } }, "ImageContent": { "type": "object", "required": [ "data", "mimeType" ], "properties": { "annotations": { "allOf": [ { "$ref": "#/components/schemas/Annotations" } ] }, "data": { "type": "string" }, "mimeType": { "type": "string" } } }, "InspectJobResponse": { "type": "object", "properties": { "processStartTime": { "type": "string", "nullable": true }, "runningDurationSeconds": { "type": "integer", "format": "int64", "nullable": true }, "sessionId": { "type": "string", "nullable": true } } }, "KillJobResponse": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ListSchedulesResponse": { "type": "object", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledJob" } } } }, "Message": { "type": "object", "description": "A message to or from an LLM", "required": [ "role", "created", "content" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/MessageContent" } }, "created": { "type": "integer", "format": "int64" }, "id": { "type": "string", "nullable": true }, "role": { "$ref": "#/components/schemas/Role" } } }, "MessageContent": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextContent" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ImageContent" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolRequest" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "toolRequest" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolResponse" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "toolResponse" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolConfirmationRequest" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "toolConfirmationRequest" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/FrontendToolRequest" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "frontendToolRequest" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ThinkingContent" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "thinking" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/RedactedThinkingContent" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "redactedThinking" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ContextLengthExceeded" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "contextLengthExceeded" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/SummarizationRequested" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "summarizationRequested" ] } } } ] } ], "description": "Content passed inside a message, which can be both simple content and tool content", "discriminator": { "propertyName": "type" } }, "ModelInfo": { "type": "object", "description": "Information about a model's capabilities", "required": [ "name", "context_limit" ], "properties": { "context_limit": { "type": "integer", "description": "The maximum context length this model supports", "minimum": 0 }, "currency": { "type": "string", "description": "Currency for the costs (default: \"$\")", "nullable": true }, "input_token_cost": { "type": "number", "format": "double", "description": "Cost per token for input (optional)", "nullable": true }, "name": { "type": "string", "description": "The name of the model" }, "output_token_cost": { "type": "number", "format": "double", "description": "Cost per token for output (optional)", "nullable": true }, "supports_cache_control": { "type": "boolean", "description": "Whether this model supports cache control", "nullable": true } } }, "PermissionConfirmationRequest": { "type": "object", "required": [ "id", "action" ], "properties": { "action": { "type": "string" }, "id": { "type": "string" }, "principal_type": { "$ref": "#/components/schemas/PrincipalType" } } }, "PermissionLevel": { "type": "string", "description": "Enum representing the possible permission levels for a tool.", "enum": [ "always_allow", "ask_before", "never_allow" ] }, "PrincipalType": { "type": "string", "enum": [ "Extension", "Tool" ] }, "ProviderDetails": { "type": "object", "required": [ "name", "metadata", "is_configured" ], "properties": { "is_configured": { "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/ProviderMetadata" }, "name": { "type": "string" } } }, "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": { "$ref": "#/components/schemas/ModelInfo" }, "description": "A list of currently known models with their capabilities\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" } } } }, "Recipe": { "type": "object", "description": "A Recipe represents a personalized, user-generated agent configuration that defines\nspecific behaviors and capabilities within the Goose system.\n\n# Fields\n\n## Required Fields\n* `version` - Semantic version of the Recipe file format (defaults to \"1.0.0\")\n* `title` - Short, descriptive name of the Recipe\n* `description` - Detailed description explaining the Recipe's purpose and functionality\n* `Instructions` - Instructions that defines the Recipe's behavior\n\n## Optional Fields\n* `prompt` - the initial prompt to the session to start with\n* `extensions` - List of extension configurations required by the Recipe\n* `context` - Supplementary context information for the Recipe\n* `activities` - Activity labels that appear when loading the Recipe\n* `author` - Information about the Recipe's creator and metadata\n* `parameters` - Additional parameters for the Recipe\n* `response` - Response configuration including JSON schema validation\n* `retry` - Retry configuration for automated validation and recovery\n# Example\n\n\nuse goose::recipe::Recipe;\n\n// Using the builder pattern\nlet recipe = Recipe::builder()\n.title(\"Example Agent\")\n.description(\"An example Recipe configuration\")\n.instructions(\"Act as a helpful assistant\")\n.build()\n.expect(\"Missing required fields\");\n\n// Or using struct initialization\nlet recipe = Recipe {\nversion: \"1.0.0\".to_string(),\ntitle: \"Example Agent\".to_string(),\ndescription: \"An example Recipe configuration\".to_string(),\ninstructions: Some(\"Act as a helpful assistant\".to_string()),\nprompt: None,\nextensions: None,\ncontext: None,\nactivities: None,\nauthor: None,\nsettings: None,\nparameters: None,\nresponse: None,\nsub_recipes: None,\nretry: None,\n};\n", "required": [ "title", "description" ], "properties": { "activities": { "type": "array", "items": { "type": "string" }, "nullable": true }, "author": { "allOf": [ { "$ref": "#/components/schemas/Author" } ], "nullable": true }, "context": { "type": "array", "items": { "type": "string" }, "nullable": true }, "description": { "type": "string" }, "extensions": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionConfig" }, "nullable": true }, "instructions": { "type": "string", "nullable": true }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeParameter" }, "nullable": true }, "prompt": { "type": "string", "nullable": true }, "response": { "allOf": [ { "$ref": "#/components/schemas/Response" } ], "nullable": true }, "retry": { "allOf": [ { "$ref": "#/components/schemas/RetryConfig" } ], "nullable": true }, "settings": { "allOf": [ { "$ref": "#/components/schemas/Settings" } ], "nullable": true }, "sub_recipes": { "type": "array", "items": { "$ref": "#/components/schemas/SubRecipe" }, "nullable": true }, "title": { "type": "string" }, "version": { "type": "string" } } }, "RecipeParameter": { "type": "object", "required": [ "key", "input_type", "requirement", "description" ], "properties": { "default": { "type": "string", "nullable": true }, "description": { "type": "string" }, "input_type": { "$ref": "#/components/schemas/RecipeParameterInputType" }, "key": { "type": "string" }, "requirement": { "$ref": "#/components/schemas/RecipeParameterRequirement" } } }, "RecipeParameterInputType": { "type": "string", "enum": [ "string", "number", "boolean", "date", "file" ] }, "RecipeParameterRequirement": { "type": "string", "enum": [ "required", "optional", "user_prompt" ] }, "RedactedThinkingContent": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" } } }, "ResourceContents": { "oneOf": [ { "type": "object", "required": [ "uri", "text" ], "properties": { "mime_type": { "type": "string", "nullable": true }, "text": { "type": "string" }, "uri": { "type": "string" } } }, { "type": "object", "required": [ "uri", "blob" ], "properties": { "blob": { "type": "string" }, "mime_type": { "type": "string", "nullable": true }, "uri": { "type": "string" } } } ] }, "Response": { "type": "object", "properties": { "json_schema": { "nullable": true } } }, "RetryConfig": { "type": "object", "description": "Configuration for retry logic in recipe execution", "required": [ "max_retries", "checks" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/SuccessCheck" }, "description": "List of success checks to validate recipe completion" }, "max_retries": { "type": "integer", "format": "int32", "description": "Maximum number of retry attempts before giving up", "minimum": 0 }, "on_failure": { "type": "string", "description": "Optional shell command to run on failure for cleanup", "nullable": true }, "on_failure_timeout_seconds": { "type": "integer", "format": "int64", "description": "Timeout in seconds for on_failure commands (default: 600 seconds)", "nullable": true, "minimum": 0 }, "timeout_seconds": { "type": "integer", "format": "int64", "description": "Timeout in seconds for individual shell commands (default: 300 seconds)", "nullable": true, "minimum": 0 } } }, "Role": { "oneOf": [ { "type": "string" }, { "type": "string" } ] }, "RunNowResponse": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } }, "ScheduledJob": { "type": "object", "required": [ "id", "source", "cron" ], "properties": { "cron": { "type": "string" }, "current_session_id": { "type": "string", "nullable": true }, "currently_running": { "type": "boolean" }, "execution_mode": { "type": "string", "nullable": true }, "id": { "type": "string" }, "last_run": { "type": "string", "format": "date-time", "nullable": true }, "paused": { "type": "boolean" }, "process_start_time": { "type": "string", "format": "date-time", "nullable": true }, "source": { "type": "string" } } }, "SessionDisplayInfo": { "type": "object", "required": [ "id", "name", "createdAt", "workingDir", "messageCount" ], "properties": { "accumulatedInputTokens": { "type": "integer", "format": "int32", "nullable": true }, "accumulatedOutputTokens": { "type": "integer", "format": "int32", "nullable": true }, "accumulatedTotalTokens": { "type": "integer", "format": "int32", "nullable": true }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "inputTokens": { "type": "integer", "format": "int32", "nullable": true }, "messageCount": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "outputTokens": { "type": "integer", "format": "int32", "nullable": true }, "scheduleId": { "type": "string", "nullable": true }, "totalTokens": { "type": "integer", "format": "int32", "nullable": true }, "workingDir": { "type": "string" } } }, "SessionHistoryResponse": { "type": "object", "required": [ "sessionId", "metadata", "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "List of messages in the session conversation" }, "metadata": { "$ref": "#/components/schemas/SessionMetadata" }, "sessionId": { "type": "string", "description": "Unique identifier for the session" } } }, "SessionInfo": { "type": "object", "required": [ "id", "path", "modified", "metadata" ], "properties": { "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/SessionMetadata" }, "modified": { "type": "string" }, "path": { "type": "string" } } }, "SessionListResponse": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionInfo" }, "description": "List of available session information objects" } } }, "SessionMetadata": { "type": "object", "description": "Metadata for a session, stored as the first line in the session file", "required": [ "working_dir", "description", "message_count" ], "properties": { "accumulated_input_tokens": { "type": "integer", "format": "int32", "description": "The number of input tokens used in the session. Accumulated across all messages.", "nullable": true }, "accumulated_output_tokens": { "type": "integer", "format": "int32", "description": "The number of output tokens used in the session. Accumulated across all messages.", "nullable": true }, "accumulated_total_tokens": { "type": "integer", "format": "int32", "description": "The total number of tokens used in the session. Accumulated across all messages (useful for tracking cost over an entire session).", "nullable": true }, "description": { "type": "string", "description": "A short description of the session, typically 3 words or less" }, "input_tokens": { "type": "integer", "format": "int32", "description": "The number of input tokens used in the session. Retrieved from the provider's last usage.", "nullable": true }, "message_count": { "type": "integer", "description": "Number of messages in the session", "minimum": 0 }, "output_tokens": { "type": "integer", "format": "int32", "description": "The number of output tokens used in the session. Retrieved from the provider's last usage.", "nullable": true }, "project_id": { "type": "string", "description": "ID of the project this session belongs to, if any", "nullable": true }, "schedule_id": { "type": "string", "description": "ID of the schedule that triggered this session, if any", "nullable": true }, "total_tokens": { "type": "integer", "format": "int32", "description": "The total number of tokens used in the session. Retrieved from the provider's last usage.", "nullable": true }, "working_dir": { "type": "string", "description": "Working directory for the session", "example": "/home/user/sessions/session1" } } }, "SessionsQuery": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int32", "minimum": 0 } } }, "Settings": { "type": "object", "properties": { "goose_model": { "type": "string", "nullable": true }, "goose_provider": { "type": "string", "nullable": true }, "temperature": { "type": "number", "format": "float", "nullable": true } } }, "SubRecipe": { "type": "object", "required": [ "name", "path" ], "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "sequential_when_repeated": { "type": "boolean" }, "values": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true } } }, "SuccessCheck": { "oneOf": [ { "type": "object", "description": "Execute a shell command and check its exit status", "required": [ "command", "type" ], "properties": { "command": { "type": "string", "description": "The shell command to execute" }, "type": { "type": "string", "enum": [ "Shell" ] } } } ], "description": "A single success check to validate recipe completion", "discriminator": { "propertyName": "type" } }, "SummarizationRequested": { "type": "object", "required": [ "msg" ], "properties": { "msg": { "type": "string" } } }, "TextContent": { "type": "object", "required": [ "text" ], "properties": { "annotations": { "allOf": [ { "$ref": "#/components/schemas/Annotations" } ] }, "text": { "type": "string" } } }, "ThinkingContent": { "type": "object", "required": [ "thinking", "signature" ], "properties": { "signature": { "type": "string" }, "thinking": { "type": "string" } } }, "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 } } }, "ToolConfirmationRequest": { "type": "object", "required": [ "id", "toolName", "arguments" ], "properties": { "arguments": {}, "id": { "type": "string" }, "prompt": { "type": "string", "nullable": true }, "toolName": { "type": "string" } } }, "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 } } }, "ToolPermission": { "type": "object", "required": [ "tool_name", "permission" ], "properties": { "permission": { "$ref": "#/components/schemas/PermissionLevel" }, "tool_name": { "type": "string" } } }, "ToolRequest": { "type": "object", "required": [ "id", "toolCall" ], "properties": { "id": { "type": "string" }, "toolCall": { "type": "object" } } }, "ToolResponse": { "type": "object", "required": [ "id", "toolResult" ], "properties": { "id": { "type": "string" }, "toolResult": { "type": "object" } } }, "ToolResultSchema": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "type": "object" }, "message": { "type": "string", "example": "Operation completed successfully", "nullable": true }, "success": { "type": "boolean", "example": true } }, "example": { "data": {}, "success": true } }, "UpdateScheduleRequest": { "type": "object", "required": [ "cron" ], "properties": { "cron": { "type": "string" } } }, "UpsertConfigQuery": { "type": "object", "required": [ "key", "value", "is_secret" ], "properties": { "is_secret": { "type": "boolean" }, "key": { "type": "string" }, "value": {} } }, "UpsertPermissionsQuery": { "type": "object", "required": [ "tool_permissions" ], "properties": { "tool_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolPermission" } } } } } } }