> ## Documentation Index
> Fetch the complete documentation index at: https://gaia-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Direct REST API usage

Use GAIA's REST API directly without any SDK.

## Authentication

Include your API key in headers:

```bash theme={null}
Authorization: Bearer gaia_your_api_key
```

## Chat Completion

```bash theme={null}
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:

```json theme={null}
{
  "id": "chat_...",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    }
  }]
}
```

## Streaming

```bash theme={null}
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:

```bash theme={null}
# 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:

```typescript theme={null}
POST /api/auth/create-key
{
  "name": "my-app"
}
```

Use it in headers:

```typescript theme={null}
Authorization: Bearer gaia_...
```

## Basic Usage

### 1. Create a Project (Agent)

```typescript theme={null}
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

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

### 3. Chat with OpenAI SDK

```typescript theme={null}
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](/integration/openai-sdk) 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](/api-reference/overview) for all endpoints.