Skip to main content
Use GAIA’s REST API directly without any SDK.

​
Authentication

Include your API key in headers: 
Authorization: Bearer gaia_your_api_key

​
Chat Completion

curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Authorization: Bearer gaia_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "proj_abc123",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
Response: 
{
  "id": "chat_...",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    }
  }]
}

​
Streaming

curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Authorization: Bearer gaia_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "proj_abc123",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
Run GAIA as an API server and integrate it into your applications.

​
Setup

Start GAIA in headless mode: 
# Local
npm run start:headless

# Docker
docker run -p 3000:3000 -e HEADLESS=true gaiaai/gaia
GAIA runs on http://localhost:3000 with no UI, just API endpoints.

​
Authentication

Get your API key: 
POST /api/auth/create-key
{
  "name": "my-app"
}
Use it in headers: 
Authorization: Bearer gaia_...

​
Basic Usage

​
1. Create a Project (Agent)

const project = await fetch('http://localhost:3000/api/projects/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gaia_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "My Agent",
    model: "gpt-4",
    provider: "openai"
  })
});

​
2. Add Knowledge

await fetch('http://localhost:3000/api/knowledge/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer gaia_...' },
  body: formData // your files
});

​
3. Chat with OpenAI SDK

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:3000/api/v1',
  apiKey: 'gaia_...'
});

const completion = await client.chat.completions.create({
  model: "proj_123", // your project ID
  messages: [{ role: "user", content: "Hello!" }]
});

​
Why Headless?

  • Backend integration - Use GAIA in your server
  • Custom UIs - Build your own interface
  • Microservices - Deploy as part of your architecture
  • API-first - Everything configurable via API
See Integration guides for SDK examples. Returns Server-Sent Events (SSE).

​
Other Operations

  • Upload Knowledge: POST /api/knowledge/upload
  • Create Tools: POST /api/tools/create
  • Add MCP Servers: POST /api/mcp/add-server
  • Manage Projects: POST /api/projects/create
See full API Reference for all endpoints.