Complete API reference for integrating the AI Gateway into any application.

API Reference

Integrate the AI Gateway into any application using a simple REST API.

Authentication

Every request must include your channel's API key in the

text

X-API-Key

header. Each channel has its own API key — find it on the channel overview card. Keys use the

text

amgai_

prefix and are AES-256 encrypted at rest.

⚠️ Important: Keep your API key secret. Do not expose it in client-side browser code for public-facing sites. Use a backend proxy instead.


http
X-API-Key: amgai_your-channel-key-here

Chat Endpoint

text

POST /api/chat

Send a user message and receive an AI reply. Use a consistent

text

session_id

to maintain conversation history across requests.

Request Body (JSON)

Field	Type	Required	Description
text `message`	string	Yes	The user's message. Max 2,000 characters.
text `session_id`	string	Yes	A unique ID for the user's conversation session. Use the same ID across requests to maintain context. Max 255 characters.
text `metadata`	object	No	Optional context passed to the agent.
text `metadata.url`	string	No	Current page URL.
text `metadata.title`	string	No	Current page title.

Response (200 OK)

Field	Type	Description
text `reply`	string	The AI's response message.
text `session_id`	string	The session ID echoed back from your request.

[!TIP] The
text
reply
field often contains Markdown. We recommend using a library like marked or react-markdown to render these correctly.

History Endpoint

text

GET /api/history?session_id={session_id}

Retrieve the full message history for a session. Useful for restoring chat state when a user revisits a page.

Query Parameters

Parameter	Type	Required	Description
text `session_id`	string	Yes	The session ID used in text `/api/chat` requests.

Response (200 OK)


json
{
  "messages": [
    { "role": "user", "content": "Hello!", "created_at": "2026-04-05T10:00:00Z" },
    { "role": "assistant", "content": "Hi! How can I help?", "created_at": "2026-04-05T10:00:01Z" }
  ]
}

Returns

text

{ "messages": [] }

if the session has no history or has expired.

Available Models

Each channel can be configured to use one of the models below. The model is selected when creating or editing a channel and applies to all conversations on that channel.

Model	Model ID	Context	Max output	Speed	Best For
Llama 3.3 70B	text `llama-3.3-70b-versatile`	128K	8K	~180 TPS	General purpose, reasoning
Llama 3.1 70B	text `llama-3.1-70b-versatile`	128K	8K	~150 TPS	Complex tasks, code generation
Llama 3.2 90B	text `llama-3.2-90b-text-preview`	128K	8K	~100 TPS	Large context tasks
Mixtral 8x7B	text `mixtral-8x7b-32768`	32K	32K	~200 TPS	Fast responses, coding
Gemma 2 9B	text `gemma2-9b-it`	8K	4K	~250 TPS	Lightweight, fast tasks

Code Examples

cURL


bash
curl -X POST https://ai.vindex.ai/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: amgai_your-channel-key-here" \
  -d '{
    "message": "Hello! What can you help me with?",
    "session_id": "user-session-abc123"
  }'

JavaScript


javascript
const response = await fetch('https://ai.vindex.ai/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'amgai_your-channel-key-here',
  },
  body: JSON.stringify({
    message: 'Hello! What can you help me with?',
    session_id: 'user-session-abc123',
  }),
});

const data = await response.json();
console.log(data.reply);

Python


python
import requests

response = requests.post(
    'https://ai.vindex.ai/api/chat',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'amgai_your-channel-key-here',
    },
    json={
        'message': 'Hello! What can you help me with?',
        'session_id': 'user-session-abc123',
    },
)

data = response.json()
print(data['reply'])

PHP


php
<?php

$response = file_get_contents('https://ai.vindex.ai/api/chat', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => implode("\r\n", [
            'Content-Type: application/json',
            'X-API-Key: amgai_your-channel-key-here',
        ]),
        'content' => json_encode([
            'message'    => 'Hello! What can you help me with?',
            'session_id' => 'user-session-abc123',
        ]),
    ],
]));

$data = json_decode($response, true);
echo $data['reply'];

Error Responses

All errors return a JSON object with an

text

error

field describing what went wrong.

Status	Cause	Response
401	No API key header	text `{ "error": "Missing API key" }`
401	Wrong or malformed API key	text `{ "error": "Invalid API key" }`
403	Site disabled	text `{ "error": "Site is inactive" }`
403	Credits exhausted	text `{ "error": "..." }`
429	Too many requests (per minute)	text `{ "error": "Rate limit exceeded" }`
429	Daily quota reached	text `{ "error": "Daily limit exceeded" }`
500	AI provider error	text `{ "error": "AI service error. Please try again." }`

Session Management Tip

Generate a unique

text

session_id

per user session (e.g. a UUID stored in localStorage or a server-side session). The gateway uses this ID to maintain conversation context for up to 24 hours. After that, a new conversation thread will be created automatically.