Skip to main content
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: 
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 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 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 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: 
{
  "id": "session-123",
  "name": "My Chat",
  "created_at": "2026-03-04T10:00:00Z"
}
Error responses follow this structure: 
{
  "message": "Session not found"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeMeaning
200Success
201Created
204No Content (success with no response body)
400Bad Request
401Unauthorized
404Not Found
424Failed Dependency (agent not initialized)
500Internal 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

Build docs developers (and LLMs) love

Get started for freeTalk to us