Agent API

REST API endpoints for managing Goose agents

The Agent API provides endpoints for controlling the agent lifecycle, managing extensions, and interacting with tools.

Start Agent

Create a new agent session.

POST /agent/start

Request Body

{
  "working_dir": "/path/to/project",
  "recipe": {
    "name": "my-task",
    "instructions": "Help with coding"
  },
  "recipe_id": "recipe-123",
  "recipe_deeplink": "goose://...",
  "extension_overrides": [
    {
      "name": "filesystem",
      "type": "builtin",
      "description": "File operations"
    }
  ]
}

Response

Returns a Session object:

{
  "id": "session-abc123",
  "name": "New Chat",
  "working_dir": "/path/to/project",
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T10:00:00Z"
}

Example

curl -X POST http://localhost:8080/agent/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "working_dir": "/home/user/project"
  }'

Resume Agent

Resume an existing agent session and load its model/extensions.

POST /agent/resume

Request Body

{
  "session_id": "session-abc123",
  "load_model_and_extensions": true
}

Response

{
  "session": {
    "id": "session-abc123",
    "name": "My Chat"
  },
  "extension_results": [
    {
      "name": "filesystem",
      "success": true
    }
  ]
}

Example

curl -X POST http://localhost:8080/agent/resume \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "load_model_and_extensions": true
  }'

Stop Agent

Stop a running agent and clean up resources.

POST /agent/stop

Request Body

{
  "session_id": "session-abc123"
}

Example

curl -X POST http://localhost:8080/agent/stop \
  -H "Content-Type: application/json" \
  -d '{"session_id": "session-abc123"}'

Restart Agent

Restart an agent, reloading its configuration and extensions.

POST /agent/restart

Request Body

{
  "session_id": "session-abc123"
}

Response

{
  "extension_results": [
    {
      "name": "filesystem",
      "success": true
    }
  ]
}

Update Provider

Change the AI model provider for an agent.

POST /agent/update_provider

Request Body

{
  "session_id": "session-abc123",
  "provider": "openai",
  "model": "gpt-4",
  "context_limit": 128000,
  "request_params": {
    "temperature": 0.7
  }
}

Example

curl -X POST http://localhost:8080/agent/update_provider \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022"
  }'

Update Working Directory

Change the agent’s working directory.

POST /agent/update_working_dir

Request Body

{
  "session_id": "session-abc123",
  "working_dir": "/new/path"
}

List Tools

Get all available tools for a session.

GET /agent/tools?session_id={session_id}&extension_name={name}

Query Parameters

• session_id (required): Session identifier
• extension_name (optional): Filter tools by extension

Response

[
  {
    "name": "read_file",
    "description": "Read contents of a file",
    "parameters": ["path"],
    "permission": "allowed"
  }
]

Example

curl "http://localhost:8080/agent/tools?session_id=session-abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Call Tool

Directly call a tool (useful for UI integrations).

POST /agent/call_tool

Request Body

{
  "session_id": "session-abc123",
  "name": "read_file",
  "arguments": {
    "path": "/home/user/file.txt"
  }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "File contents here..."
    }
  ],
  "is_error": false
}

Example

curl -X POST http://localhost:8080/agent/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "name": "read_file",
    "arguments": {"path": "README.md"}
  }'

Read Resource

Read a resource from an MCP server.

POST /agent/read_resource

Request Body

{
  "session_id": "session-abc123",
  "extension_name": "filesystem",
  "uri": "file:///path/to/file"
}

Response

{
  "uri": "file:///path/to/file",
  "mime_type": "text/plain",
  "text": "Resource contents..."
}

Add Extension

Dynamically add an extension to a running agent.

POST /agent/add_extension

Request Body

{
  "session_id": "session-abc123",
  "config": {
    "name": "github",
    "type": "stdio",
    "description": "GitHub integration",
    "cmd": "mcp-server-github",
    "args": []
  }
}

Example

curl -X POST http://localhost:8080/agent/add_extension \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "config": {
      "name": "memory",
      "type": "builtin",
      "description": "Memory management"
    }
  }'

Remove Extension

Remove an extension from a running agent.

POST /agent/remove_extension

Request Body

{
  "session_id": "session-abc123",
  "name": "github"
}

Example

curl -X POST http://localhost:8080/agent/remove_extension \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "name": "memory"
  }'

List Apps

Get available MCP apps from loaded extensions.

GET /agent/list_apps?session_id={session_id}

Response

{
  "apps": [
    {
      "resource": {
        "name": "my-app",
        "uri": "ui://apps/my-app"
      },
      "mcp_servers": ["server-1"]
    }
  ]
}

Export App

Export an MCP app as HTML.

GET /agent/export_app/{name}

Response

Returns HTML string of the app.

Import App

Import an MCP app from HTML.

POST /agent/import_app

Request Body

{
  "html": "<html>...</html>"
}

Response

{
  "name": "imported-app",
  "message": "App 'imported-app' imported successfully"
}

Error Responses

All endpoints may return these error codes:

Code	Description
400	Bad request - invalid parameters
401	Unauthorized - invalid API key
404	Resource not found
424	Failed Dependency - agent not initialized
500	Internal server error

Error Response Format

{
  "message": "Agent not initialized"
}