API Server

Source Code: src/gaia/api/

The GAIA API Server exposes GAIA agents as “models” through an OpenAI-compatible REST API, enabling integration with VSCode extensions and other OpenAI-compatible clients.

Technical Specifications: API Server Specification

Quick Start

The server exposes one model, gaia — the flagship agent. Capability that used to mean picking a different agent is now a skill it loads on demand. Register more in AGENT_MODELS (src/gaia/api/agent_registry.py); see Adding New Agents.

Start GAIA API Server

This brings up Lemonade Server through the daemon, at the context size your device profile pins — nothing to start beforehand.

gaia api start

Test the Server

curl http://localhost:8080/health

curl http://localhost:8080/v1/models

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "messages": [{"role": "user", "content": "Write a hello world function"}]
  }'

The health response includes API, Lemonade LLM, and RAG component status. A running API returns HTTP 200 with top-level status degraded when Lemonade is unavailable or has no LLM loaded.

Prerequisites

GAIA Installation

Install GAIA with API support:

uv pip install -e ".[api]"

Installs FastAPI and Uvicorn required for the API server.

Lemonade Server

Must be installed — the API server starts it through the daemon and sizes the context from your device profile:

gaia init

Required Models: Download Gemma-4-E4B-it-GGUF via Lemonade’s model manager

Server Management

Start Server

Basic
Background
Debug
Custom

Start in foreground:

gaia api start

gaia api start has no --background flag — detach via your shell (only gaia mcp start supports --background natively):

# Unix: use nohup + &
nohup gaia api start > api.log 2>&1 &

# Windows: start a detached PowerShell process
Start-Process -NoNewWindow gaia -ArgumentList "api","start"

Start with debug logging:

gaia api start --debug

Custom host/port:

gaia api start --host 0.0.0.0 --port 8888

Check Status

gaia api status

Stop Server

gaia api stop

Usage Examples

Python (OpenAI Client)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Create a REST API with Express and SQLite"}]
)

print(response.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Create a Django REST API with authentication"}]
)

print(response.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

stream = client.chat.completions.create(
    model="your-agent-id",
    messages=[{"role": "user", "content": "Write a calculator class"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript/Node.js

const axios = require('axios');

async function chat(message) {
    const response = await axios.post(
        'http://localhost:8080/v1/chat/completions',
        {
            model: 'your-agent-id',
            messages: [{ role: 'user', content: message }]
        }
    );
    return response.data.choices[0].message.content;
}

chat('Build me a todo app using nextjs').then(console.log);

chat('Write a Python function to calculate factorial').then(console.log);

async function chat(message) {
    const response = await fetch('http://localhost:8080/v1/chat/completions', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            model: 'your-agent-id',
            messages: [{ role: 'user', content: message }]
        })
    });
    const data = await response.json();
    return data.choices[0].message.content;
}

cURL

Non-Streaming
Streaming

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "messages": [{"role": "user", "content": "Write a function"}]
  }'

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-id",
    "messages": [{"role": "user", "content": "Write a function"}],
    "stream": true
  }'

Available Models

Model	Agent	What it does
`gaia`	`GaiaAgent`	Conversation, document Q&A, data analysis, web research, memory, and skills

Register additional agents in AGENT_MODELS (src/gaia/api/agent_registry.py) to expose them as selectable models. How to add one: API Server Specification → Adding New Agents

Troubleshooting

Server Won't Start

Check if port is in use:

Mac/Linux
Windows

lsof -i :8080

netstat -ano | findstr :8080

Try different port:

gaia api start --port 8888

Connection Refused

Verify server is running:

gaia api status

Check health endpoint:

curl http://localhost:8080/health

Check components.llm when the top-level status is degraded.

Agent Errors

Check Lemonade is running:

gaia daemon status

Start it if it isn’t:

gaia daemon start

Enable debug mode:

gaia api start --debug

Common Issues

Issue	Solution
”Model not found”	Confirm the model id is registered in `AGENT_MODELS` — `GET /v1/models` lists what’s actually available
”Agent processing failed”	Check the model server with `gaia daemon status`; start it with `gaia daemon start`
”Port already in use”	Stop existing server or use `--port` flag
Streaming not working	Ensure `"stream": true` in request

More help: FAQ

VSCode Integration

VSCode Extension

Use a registered GAIA agent directly in Visual Studio Code with the Language Model Provider extension

Quick Setup:

Start the API Server

It brings up Lemonade Server through the daemon, so this is the only command you need:

gaia api start

Install Extension

Build and install the GAIA VSCode extension→ VSCode Integration Guide

Select Model

Select GAIA models from VSCode’s model picker

Technical Documentation

API Specification

Complete API reference with request/response formats

Development Guide

Development and contribution guidelines

Command Line

API & Development

Help

Quick Start

Prerequisites

GAIA Installation

Lemonade Server

Server Management

Start Server

Check Status

Stop Server

Usage Examples

Python (OpenAI Client)

JavaScript/Node.js

cURL

Available Models

Troubleshooting

Common Issues

VSCode Integration

VSCode Extension

Technical Documentation

API Specification

Development Guide

​Quick Start

​Prerequisites

GAIA Installation

Lemonade Server

​Server Management

​Start Server

​Check Status

​Stop Server

​Usage Examples

​Python (OpenAI Client)

​JavaScript/Node.js

​cURL

​Available Models

​Troubleshooting

​Common Issues

​VSCode Integration

VSCode Extension

​Technical Documentation

API Specification

Development Guide

Quick Start

Prerequisites

Server Management

Start Server

Check Status

Stop Server

Usage Examples

Python (OpenAI Client)

JavaScript/Node.js

cURL

Available Models

Troubleshooting

Common Issues

VSCode Integration

Technical Documentation