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

# API Specification

> Complete OpenAI-compatible REST API reference for GAIA agents

<Info>
  **Source Code:** [`src/gaia/api/`](https://github.com/amd/gaia/tree/main/src/gaia/api)
</Info>

<Badge text="development" color="orange" />

<Info>
  The GAIA API Server implements a subset of OpenAI's Chat Completions API with GAIA agents exposed as "models".
</Info>

**Base URL:** `http://localhost:8080` (default)

**Architecture:**

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

***

## Endpoints

### Health Check

<Card title="GET /health" icon="heart-pulse">
  Check server health status
</Card>

**Response:**

```json theme={null}
{
  "status": "ok",
  "service": "gaia-api"
}
```

**Example:**

```bash theme={null}
curl http://localhost:8080/health
```

***

### List Models

<Card title="GET /v1/models" icon="list">
  List available GAIA agent models
</Card>

**Response Schema:**

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

**Example:**

```bash theme={null}
curl http://localhost:8080/v1/models
```

***

### Chat Completions

<Card title="POST /v1/chat/completions" icon="comments">
  Create chat completion using a GAIA agent
</Card>

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

#### Request Parameters

| Parameter     | Type    | Required | Default | Range     | Description                         |
| ------------- | ------- | -------- | ------- | --------- | ----------------------------------- |
| `model`       | string  | ✅ Yes    | -       | -         | Model ID (e.g., "gaia-code")        |
| `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

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    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 function"}],
        "stream": false
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1677652288,
      "model": "gaia-code",
      "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
      }
    }
    ```
  </Tab>
</Tabs>

***

#### Streaming Response

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    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 function"}],
        "stream": true
      }'
    ```
  </Tab>

  <Tab title="Response (SSE)">
    ```
    data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gaia-code","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

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

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

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

    data: [DONE]
    ```
  </Tab>
</Tabs>

***

## Available Models

### gaia-code

<Card title="Autonomous Code Development" icon="code">
  Python/TypeScript development agent with intelligent routing
</Card>

| Property              | Value                                                                            |
| --------------------- | -------------------------------------------------------------------------------- |
| **ID**                | `gaia-code`                                                                      |
| **Max Input Tokens**  | 32768                                                                            |
| **Max Output Tokens** | 8192                                                                             |
| **Description**       | Autonomous Python/TypeScript coding agent with planning, generation, and testing |

**Requirements:**

* Lemonade Server with `--ctx-size 32768`
* Model: `Qwen3.5-35B-A3B-GGUF`

**Capabilities:**

* Code generation (functions, classes, projects)
* Test generation
* Linting & formatting (pylint, Black)
* Error detection and correction
* Project scaffolding
* Architectural planning

***

## Error Responses

All errors follow OpenAI's error format.

### 400 - Bad Request

```json theme={null}
{
  "error": {
    "message": "messages is required",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}
```

### 404 - Model Not Found

```json theme={null}
{
  "error": {
    "message": "Model 'gaia-invalid' not found. Available models: gaia-code",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

### 500 - Internal Server Error

```json theme={null}
{
  "error": {
    "message": "Agent processing failed: <details>",
    "type": "internal_error",
    "code": "agent_error"
  }
}
```

***

## OpenAI API Compatibility

### Supported Features

<CardGroup cols={2}>
  <Card title="✅ Supported" icon="check">
    * `/v1/chat/completions` (streaming & non-streaming)
    * `/v1/models`
    * `messages` array with roles
    * `temperature`, `max_tokens`, `top_p`
    * Server-Sent Events (SSE) streaming
  </Card>

  <Card title="❌ Not Supported" icon="xmark">
    * `frequency_penalty`, `presence_penalty`
    * `functions` and `tools` parameters
    * `response_format` parameter
    * `logprobs`, `n`, `stop` parameters
    * `/v1/embeddings`, `/v1/audio/*`, `/v1/images/*`
  </Card>
</CardGroup>

***

## Adding New Agents

<Steps>
  <Step title="Create Agent Class">
    ```python theme={null}
    # 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,
            }
    ```
  </Step>

  <Step title="Register in Agent Registry">
    ```python theme={null}
    # 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"
        }
    }
    ```
  </Step>

  <Step title="Restart Server">
    ```bash theme={null}
    gaia api stop
    gaia api start
    ```
  </Step>
</Steps>

***

## Security

<Warning>
  **Designed for local development only.** Not production-ready.
</Warning>

**Current Implementation:**

* ❌ No authentication
* ❌ No rate limiting
* ✅ CORS enabled (all origins)

**For Production Deployment:**

* Implement API key authentication
* Add rate limiting middleware
* Configure CORS restrictions
* Use HTTPS with valid certificates

***

## See Also

<CardGroup cols={2}>
  <Card title="API Server Guide" icon="server" href="/docs/reference/api">
    Usage examples and integration guides
  </Card>

  <Card title="Code Agent" icon="code" href="/docs/guides/code">
    Code agent capabilities
  </Card>

  <Card title="Routing Guide" icon="route" href="/docs/guides/routing">
    Intelligent language detection
  </Card>

  <Card title="VSCode Integration" icon="code" href="/docs/integrations/vscode">
    VSCode extension setup
  </Card>
</CardGroup>

***

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>