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

# Server API Overview

> Introduction to the Goose server REST API for agent control and management

The Goose server exposes a comprehensive REST API for managing AI agents, sessions, and configurations. The server (`goosed`) runs as a backend service that handles agent lifecycle, conversation management, and extension coordination.

## Base URL

By default, the Goose server runs on:

```
http://localhost:8080
```

## Authentication

Most endpoints require authentication via an API key passed in the request headers:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/status
```

The secret key is generated when the server starts and can be found in the server logs or configuration.

## API Categories

The Goose server API is organized into several main categories:

### Agent Management

Control the agent lifecycle and capabilities:

* Start, stop, and restart agents
* Update AI providers and models
* Manage extensions (MCP servers)
* Call tools and read resources
* Handle working directory changes

See [Agent Endpoints](/api/server/agents) for details.

### Session Management

Manage conversation sessions and history:

* List and search sessions
* Create, fork, and delete sessions
* Import/export session data
* Update session metadata
* Manage session extensions

See [Session Endpoints](/api/server/sessions) for details.

### Real-time Communication

Stream agent responses and events:

* Server-Sent Events (SSE) for message streaming
* Real-time token usage updates
* Tool execution notifications
* Model change events

See [WebSocket & Streaming](/api/server/websocket) for details.

### Configuration Management

* Provider setup and configuration
* Extension management
* Prompt customization
* Permission settings
* Model catalog access

### Additional Features

* **Recipes**: Automated task workflows
* **Scheduling**: Cron-based recipe execution
* **Dictation**: Audio transcription
* **Local Inference**: Download and manage local LLM models
* **Telemetry**: Usage analytics and diagnostics

## Response Format

All API responses use JSON format:

```json theme={null}
{
  "id": "session-123",
  "name": "My Chat",
  "created_at": "2026-03-04T10:00:00Z"
}
```

Error responses follow this structure:

```json theme={null}
{
  "message": "Session not found"
}
```

## HTTP Status Codes

The API uses standard HTTP status codes:

| Code  | Meaning                                    |
| ----- | ------------------------------------------ |
| `200` | Success                                    |
| `201` | Created                                    |
| `204` | No Content (success with no response body) |
| `400` | Bad Request                                |
| `401` | Unauthorized                               |
| `404` | Not Found                                  |
| `424` | Failed Dependency (agent not initialized)  |
| `500` | Internal Server Error                      |

## OpenAPI Specification

The complete OpenAPI specification is available at:

```
http://localhost:8080/openapi.json
```

You can also find it in the source code at `ui/desktop/openapi.json`.

## Common Patterns

### Starting a New Chat

1. **Start an agent** with `/agent/start` - creates a new session
2. **Resume the agent** with `/agent/resume` - loads model and extensions
3. **Send a message** with `/reply` - streams back the agent's response

### Managing Extensions

1. **List available tools** with `/agent/tools?session_id=...`
2. **Add an extension** with `/agent/add_extension`
3. **Remove an extension** with `/agent/remove_extension`

### Session Lifecycle

1. **Create session** via `/agent/start`
2. **Get session details** with `/sessions/{session_id}`
3. **Fork session** with `/sessions/{session_id}/fork` to branch conversations
4. **Export session** with `/sessions/{session_id}/export` for backup
5. **Delete session** with `/sessions/{session_id}`

## Next Steps

* [Agent API Reference](/api/server/agents) - Agent lifecycle and control
* [Session API Reference](/api/server/sessions) - Session management
* [WebSocket & Streaming](/api/server/websocket) - Real-time communication