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

Start Lemonade Server

Start with extended context for Code agent:

lemonade-server serve --ctx-size 32768

Start GAIA API Server

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": "gaia-code",
    "messages": [{"role": "user", "content": "Write a hello world function"}]
  }'

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 running with sufficient context:

lemonade-server serve --ctx-size 32768

Required Models: Download Qwen3.5-35B-A3B-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="gaia-code",
    messages=[{"role": "user", "content": "Create a REST API with Express and SQLite"}]
)

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

TypeScript/Express backend (routing detects “Express” → TypeScript)

from openai import OpenAI

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

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

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

Python backend (routing detects “Django” → Python)

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="gaia-code",
    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: 'gaia-code',
            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);

TypeScript/React frontend (routing detects “React” → TypeScript frontend)

Python script (routing detects Python for generic functions)

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: 'gaia-code',
            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": "gaia-code",
    "messages": [{"role": "user", "content": "Write a function"}]
  }'

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

Available Models

gaia-code

Autonomous Python/TypeScript development agent with intelligent routing

Property	Value
Model ID	`gaia-code`
Context	32K input / 8K output
Requirements	Lemonade with `--ctx-size 32768`
Description	Autonomous development agent with planning, generation, and testing

Intelligent Routing: The gaia-code model uses GAIA’s Routing Agent to automatically detect your target programming language (Python or TypeScript) and project type based on framework mentions.→ Learn about Routing

Full specifications: API Server Specification

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

Agent Errors

Check Lemonade is running:

curl http://localhost:13305/health

Verify context size:

lemonade-server serve --ctx-size 32768

Enable debug mode:

gaia api start --debug

Common Issues

Issue	Solution
”Model not found”	Use correct model ID: `gaia-code`
”Agent processing failed”	Ensure Lemonade is running with `--ctx-size 32768`
”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 GAIA Code directly in Visual Studio Code with the Language Model Provider extension

Quick Setup:

Start Servers

Start Lemonade server with extended context:

lemonade-server serve --ctx-size 32768

Start GAIA API server:

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

Routing Guide

Intelligent language/framework detection

Code Agent

Code agent capabilities and usage

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

gaia-code

Troubleshooting

Common Issues

VSCode Integration

VSCode Extension

Technical Documentation

API Specification

Routing Guide

Code Agent

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

gaia-code

​Troubleshooting

​Common Issues

​VSCode Integration

VSCode Extension

​Technical Documentation

API Specification

Routing Guide

Code Agent

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