AI API Reference

Complete reference for all AI-related endpoints. All endpoints require authentication.

Request Flow

Base URL

https://api.yourdomain.com

Authentication

All AI endpoints require a valid access token:

Authorization: Bearer <access-token>

---

GET /ai/providers

List all AI providers and their configuration status.

Response:

[
  {
    "provider": "anthropic",
    "defaultModel": "claude-sonnet-4-6",
    "configured": true
  },
  {
    "provider": "openai",
    "defaultModel": "gpt-4o",
    "configured": false
  },
  {
    "provider": "gemini",
    "defaultModel": "gemini-2.0-flash",
    "configured": true
  },
  {
    "provider": "groq",
    "defaultModel": "llama-3.3-70b-versatile",
    "configured": false
  }
]

configured: true means the provider's API key is present in the backend environment. Only configured providers can be used for chat requests.

Status Codes:

• 200 - Success
• 401 - Unauthorized

---

POST /ai/chat

Send a chat request and receive a complete AI response.

Request Body:

{
  "provider": "anthropic",
  "messages": [
    { "role": "user", "content": "Explain JWT in one sentence." }
  ],
  "model": "claude-sonnet-4-6",
  "maxTokens": 256,
  "temperature": 0.7,
  "systemPrompt": "You are a helpful assistant."
}

Field	Type	Required	Description
provider	string	Yes	One of: anthropic, openai, gemini, groq
messages	AIMessage[]	Yes	Conversation history
model	string	No	Model name — uses provider default if omitted
maxTokens	number	No	Maximum tokens in the response
temperature	number	No	Randomness (0–2). Lower = more deterministic
systemPrompt	string	No	System instruction prepended to the conversation

AIMessage shape:

{ "role": "user" | "assistant" | "system", "content": "..." }

Response:

{
  "content": "JWT is a compact, self-contained token format used to securely transmit information as a JSON object.",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "usage": {
    "inputTokens": 18,
    "outputTokens": 22
  }
}

Status Codes:

• 200 - Success
• 400 - Invalid request body
• 401 - Unauthorized
• 422 - Provider not configured
• 500 - Provider API error

---

POST /ai/stream

Send a chat request and receive a streaming response via Server-Sent Events (SSE).

Request Body:

Same as /ai/chat.

Response Headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Response Stream:

Each event is a JSON object on a data: line:

data: {"chunk": "JWT "}
data: {"chunk": "is a "}
data: {"chunk": "compact, "}
data: {"chunk": "self-contained token..."}
data: [DONE]

On error:

data: {"error": "Provider not configured"}

The stream terminates with data: [DONE].

Status Codes:

• 200 - Stream started (errors may appear inside the stream)
• 400 - Invalid request body
• 401 - Unauthorized

Consuming the Stream (Frontend)

The useAIChat hook handles SSE automatically:

import { useAIChat } from '@/hooks/useAIChat';

const { sendMessageStream, messages, isStreaming, stop } = useAIChat({
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
});

await sendMessageStream('Explain streaming in one sentence.');
// messages array updates in real-time as chunks arrive

Or consume directly with fetch:

const response = await fetch('/ai/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({ provider: 'openai', messages }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const lines = decoder.decode(value).split('\n');
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') return;
      const { chunk } = JSON.parse(data);
      // append chunk to UI
    }
  }
}

---

Available Models

Anthropic

Model	Description
claude-sonnet-4-6	Balanced performance and speed (default)
claude-opus-4-6	Most capable
claude-haiku-4-5-20251001	Fastest and most compact

OpenAI

Model	Description
gpt-4o	Multimodal flagship (default)
gpt-4o-mini	Faster, lower cost
o1	Advanced reasoning
o1-mini	Compact reasoning model

Google Gemini

Model	Description
gemini-2.0-flash	Fast, efficient (default)
gemini-2.5-pro	Most capable Gemini
gemini-1.5-flash	Stable flash variant

Groq

Model	Description
llama-3.3-70b-versatile	High-quality Llama 3.3 70B (default)
llama-3.1-8b-instant	Ultra-fast 8B model
mixtral-8x7b-32768	Mixtral MoE with 32k context

---

Error Responses

{
  "statusCode": 422,
  "message": "Provider 'openai' is not configured. Set OPENAI_API_KEY in your environment.",
  "error": "Unprocessable Entity"
}

Common Error Codes

Code	Description
400	Bad Request — missing or invalid fields
401	Unauthorized — missing or expired token
422	Unprocessable Entity — provider not configured
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — provider API failure

---

Rate Limits

Endpoint	Limit	Window
/ai/chat	100	1 minute
/ai/stream	100	1 minute
/ai/providers	200	1 minute

---

Related Documentation

• AI Integrations Guide - Setup and usage across all packages
• Integrations - All supported providers
• Environment Variables - API key configuration
• Authentication API - Obtaining access tokens