Skip to main content

​
Base URL

http://localhost:3030/api/v1
For production deployments, replace localhost:3030 with your server address.

​
Authentication

All API requests require authentication using a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Get your API key from the GAIA AI dashboard or by running in headless mode. Learn more about authentication →

​
API Groups

AI

Manage AI providers, models, and configurations

Chat

OpenAI-compatible chat completions and streaming

Projects

Create and manage agent projects

Knowledge

Upload, search, and manage knowledge bases

MCP

Configure Model Context Protocol servers

Tools

Create and execute custom tools

Credentials

Manage API keys and provider credentials

Prompts

Store and manage reusable prompts

​
OpenAI Compatibility

GAIA AI implements OpenAI-compatible endpoints, allowing you to use existing OpenAI SDKs: 
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:3030/api/v1/ai/chat',
  apiKey: process.env.GAIA_API_KEY
});

​
Rate Limits

Currently, GAIA AI does not enforce rate limits when self-hosted. For production deployments, consider implementing rate limiting at your reverse proxy or load balancer level.

​
Error Handling

All endpoints return standard HTTP status codes:
CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
404Not Found - Resource doesn’t exist
500Internal Server Error
Error responses follow this format: 
{
  "success": false,
  "message": "Error description",
  "error": "Detailed error information"
}

​
SDK Examples

​
TypeScript with OpenAI SDK

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:3030/api/v1/ai/chat',
  apiKey: process.env.GAIA_API_KEY
});

const completion = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Search our documentation' }
  ],
  extra_body: {
    chatId: 'chat-123'
  }
});

​
TypeScript with Vercel AI SDK

import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';

const gaia = createOpenAI({
  baseURL: 'http://localhost:3030/api/v1/ai/chat',
  apiKey: process.env.GAIA_API_KEY
});

const { text } = await generateText({
  model: gaia('gpt-4o'),
  prompt: 'What is GAIA AI?'
});

​
Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3030/api/v1/ai/chat",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Search our documentation"}
    ],
    extra_body={"chatId": "chat-123"}
)

​
Next Steps

Authentication

Learn how to authenticate your requests

Chat Completions

Start building with the chat API

Knowledge Upload

Add knowledge to your agent

Tools

Create custom tools