API Specification

Source Code: src/gaia/api/

The GAIA API Server implements a subset of OpenAI’s Chat Completions API with GAIA agents exposed as “models”.

Base URL: http://localhost:8080 (default) Architecture:

External Client → FastAPI Server → GAIA Agents → Lemonade LLM Backend

Endpoints

Health Check

GET /health

Check API, Lemonade LLM, and RAG component status

Response:

{
  "status": "ok",
  "service": "gaia-api",
  "components": {
    "api": {
      "status": "ready"
    },
    "llm": {
      "status": "ready",
      "backend": "lemonade",
      "model": "Gemma-4-E4B-it-GGUF",
      "url": "http://localhost:13305/api/v1"
    },
    "rag": {
      "status": "not_configured"
    }
  }
}

The endpoint returns HTTP 200 while the GAIA API process is serving requests. The top-level status is ok only when Lemonade has an LLM loaded, and degraded when the LLM component is unavailable or error. RAG reports not_configured until the document API is enabled. GAIA reads loaded-model state from Lemonade’s /api/v1/health endpoint with a 350 ms timeout. The /api/v1/models catalog is not used for readiness because downloaded models are not necessarily loaded. Example:

curl http://localhost:8080/health

List Models

GET /v1/models

List available GAIA agent models

Response Schema:

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "model",
      "created": 1234567890,
      "owned_by": "amd-gaia",
      "description": "string",
      "max_input_tokens": 32768,
      "max_output_tokens": 8192
    }
  ]
}

Example:

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

Chat Completions

POST /v1/chat/completions

Create chat completion using a GAIA agent

Supports both streaming (SSE) and non-streaming responses.

Request Parameters

Parameter	Type	Required	Default	Range	Description
`model`	string	✅ Yes	-	-	Model ID — an id registered in `AGENT_MODELS`
`messages`	array	✅ Yes	-	-	Array of message objects
`stream`	boolean	No	`false`	-	Enable Server-Sent Events streaming
`temperature`	number	No	`0.7`	0.0 - 2.0	Sampling temperature
`max_tokens`	integer	No	-	> 0	Maximum tokens to generate
`top_p`	number	No	`1.0`	0.0 - 1.0	Nucleus sampling parameter

Message Object

Field	Type	Required	Values	Description
`role`	string	✅ Yes	`"system"`, `"user"`, `"assistant"`, `"tool"`	Message role
`content`	string	✅ Yes	-	Message content
`tool_calls`	array	No	-	Tool calls (assistant role only)
`tool_call_id`	string	No	-	Tool call ID (tool role only)

Non-Streaming Response

Request
Response

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 function"}],
    "stream": false
  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "your-agent-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here's a hello function..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 150,
    "total_tokens": 170
  }
}

Streaming Response

Request
Response (SSE)

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 function"}],
    "stream": true
  }'

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"your-agent-id","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"your-agent-id","choices":[{"index":0,"delta":{"content":"Here"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"your-agent-id","choices":[{"index":0,"delta":{"content":"'s"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"your-agent-id","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Available Models

AGENT_MODELS in src/gaia/api/agent_registry.py holds one entry, gaia, mapping to the flagship GaiaAgent. GET /v1/models returns it. To expose another agent, add an entry — see Adding New Agents below.

Error Responses

All errors follow OpenAI’s error format.

400 - Bad Request

{
  "error": {
    "message": "messages is required",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

404 - Model Not Found

{
  "error": {
    "message": "Model 'gaia-invalid' not found. Available models: <none registered>",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

500 - Internal Server Error

{
  "error": {
    "message": "Agent processing failed: <details>",
    "type": "internal_error",
    "code": "agent_error"
  }
}

OpenAI API Compatibility

Supported Features

✅ Supported

/v1/chat/completions (streaming & non-streaming)
/v1/models
messages array with roles
temperature, max_tokens, top_p
Server-Sent Events (SSE) streaming

❌ Not Supported

frequency_penalty, presence_penalty
functions and tools parameters
response_format parameter
logprobs, n, stop parameters
/v1/embeddings, /v1/audio/*, /v1/images/*

Adding New Agents

Create Agent Class

# src/gaia/agents/myagent/agent.py
from gaia.agents.base.api_agent import ApiAgent
from gaia.agents.base.agent import Agent

class MyAgent(ApiAgent, Agent):
    def get_model_info(self):
        return {
            "max_input_tokens": 8192,
            "max_output_tokens": 4096,
        }

# src/gaia/api/agent_registry.py
AGENT_MODELS = {
    "gaia-myagent": {
        "class_name": "gaia.agents.myagent.agent.MyAgent",
        "init_params": {"silent_mode": True},
        "description": "My custom agent"
    }
}

Restart Server

gaia api stop
gaia api start

Security

Designed for local development only. Not production-ready.

Current Implementation:

⚠️ Optional API key: set GAIA_API_KEY and every chat completion must send Authorization: Bearer <key> (401 otherwise). Unset, loopback callers are allowed with a startup warning, and binding beyond loopback is refused. See Authentication.
✅ CORS limited to loopback origins; add others with GAIA_API_CORS_ORIGINS. Browser requests from any other origin are refused with 403.
❌ No rate limiting

For Production Deployment:

Set GAIA_API_KEY
Add rate limiting middleware
Use HTTPS with valid certificates

API Server Guide

Usage examples and integration guides

VSCode Integration

VSCode extension setup

Command Line

API & Development

Help

API Specification

Endpoints

Health Check

GET /health

List Models

GET /v1/models

Chat Completions

POST /v1/chat/completions

Request Parameters

Message Object

Non-Streaming Response

Streaming Response

Available Models

Error Responses

400 - Bad Request

404 - Model Not Found

500 - Internal Server Error

OpenAI API Compatibility

Supported Features

✅ Supported

❌ Not Supported

Adding New Agents

Security

See Also

API Server Guide

VSCode Integration

​Endpoints

​Health Check

GET /health

​List Models

GET /v1/models

​Chat Completions

POST /v1/chat/completions

​Request Parameters

​Message Object

​Non-Streaming Response

​Streaming Response

​Available Models

​Error Responses

​400 - Bad Request

​404 - Model Not Found

​500 - Internal Server Error

​OpenAI API Compatibility

​Supported Features

✅ Supported

❌ Not Supported

​Adding New Agents

​Security

​See Also

API Server Guide

VSCode Integration

Endpoints

Health Check

List Models

Chat Completions

Request Parameters

Message Object

Non-Streaming Response

Streaming Response

Available Models

Error Responses

400 - Bad Request

404 - Model Not Found

500 - Internal Server Error

OpenAI API Compatibility

Supported Features

Adding New Agents

Security

See Also