> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
POST /agent/start
```

### Request Body

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
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.

```http theme={null}
POST /agent/resume
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123",
  "load_model_and_extensions": true
}
```

### Response

```json theme={null}
{
  "session": {
    "id": "session-abc123",
    "name": "My Chat"
  },
  "extension_results": [
    {
      "name": "filesystem",
      "success": true
    }
  ]
}
```

### Example

```bash theme={null}
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.

```http theme={null}
POST /agent/stop
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123"
}
```

### Example

```bash theme={null}
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.

```http theme={null}
POST /agent/restart
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123"
}
```

### Response

```json theme={null}
{
  "extension_results": [
    {
      "name": "filesystem",
      "success": true
    }
  ]
}
```

## Update Provider

Change the AI model provider for an agent.

```http theme={null}
POST /agent/update_provider
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123",
  "provider": "openai",
  "model": "gpt-4",
  "context_limit": 128000,
  "request_params": {
    "temperature": 0.7
  }
}
```

### Example

```bash theme={null}
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.

```http theme={null}
POST /agent/update_working_dir
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123",
  "working_dir": "/new/path"
}
```

## List Tools

Get all available tools for a session.

```http theme={null}
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

```json theme={null}
[
  {
    "name": "read_file",
    "description": "Read contents of a file",
    "parameters": ["path"],
    "permission": "allowed"
  }
]
```

### Example

```bash theme={null}
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).

```http theme={null}
POST /agent/call_tool
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123",
  "name": "read_file",
  "arguments": {
    "path": "/home/user/file.txt"
  }
}
```

### Response

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "File contents here..."
    }
  ],
  "is_error": false
}
```

### Example

```bash theme={null}
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.

```http theme={null}
POST /agent/read_resource
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123",
  "extension_name": "filesystem",
  "uri": "file:///path/to/file"
}
```

### Response

```json theme={null}
{
  "uri": "file:///path/to/file",
  "mime_type": "text/plain",
  "text": "Resource contents..."
}
```

## Add Extension

Dynamically add an extension to a running agent.

```http theme={null}
POST /agent/add_extension
```

### Request Body

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

### Example

```bash theme={null}
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.

```http theme={null}
POST /agent/remove_extension
```

### Request Body

```json theme={null}
{
  "session_id": "session-abc123",
  "name": "github"
}
```

### Example

```bash theme={null}
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.

```http theme={null}
GET /agent/list_apps?session_id={session_id}
```

### Response

```json theme={null}
{
  "apps": [
    {
      "resource": {
        "name": "my-app",
        "uri": "ui://apps/my-app"
      },
      "mcp_servers": ["server-1"]
    }
  ]
}
```

## Export App

Export an MCP app as HTML.

```http theme={null}
GET /agent/export_app/{name}
```

### Response

Returns HTML string of the app.

## Import App

Import an MCP app from HTML.

```http theme={null}
POST /agent/import_app
```

### Request Body

```json theme={null}
{
  "html": "<html>...</html>"
}
```

### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "message": "Agent not initialized"
}
```