AI API for Developers

AI API for Developers

The Kinexa AI API allows developers to integrate AI capabilities into their applications using the Kinexa AI Gateway.

Authentication

All AI API requests require a Bearer token (JWT) obtained from Kinexa SSO:

Authorization: Bearer YOUR_JWT_TOKEN

JWT tokens are obtained by authenticating through the Kinexa SSO system. See the API Getting Started guide for details.

POST /api/ai/chat

Send a message to the AI and receive a response.

Request:

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What are your business hours?" }
  ],
  "model": "auto",
  "temperature": 0.7,
  "max_tokens": 1024
}

• model — Use "auto" to let the gateway select based on your tier, or specify: "claude-haiku", "claude-sonnet", "claude-opus", "gpt-4o", "qwen2.5", "llama3.2"
• temperature — Creativity level (0.0 = deterministic, 1.0 = creative)
• max_tokens — Maximum response length

Response:

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "content": "Our business hours are Monday to Friday, 9 AM to 5 PM WIB.",
    "model": "qwen2.5:7b",
    "provider": "ollama",
    "usage": {
      "prompt_tokens": 24,
      "completion_tokens": 18,
      "total_tokens": 42
    }
  }
}

GET /api/ai/models

List all available AI models for your tier.

Response:

{
  "success": true,
  "data": [
    { "id": "qwen2.5:7b", "provider": "ollama", "available": true },
    { "id": "claude-haiku", "provider": "anthropic", "available": false, "reason": "Requires Pro tier" }
  ]
}

GET /api/ai/health

Check the health status of all AI providers.

Response:

{
  "success": true,
  "data": {
    "ollama": { "status": "healthy", "latency_ms": 120 },
    "anthropic": { "status": "healthy", "latency_ms": 340 },
    "openai": { "status": "degraded", "latency_ms": 5200 }
  }
}

Example: JavaScript/TypeScript

const response = await fetch("https://api.kinexa.id/v1/ai/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    messages: [
      { role: "user", content: "Summarize our sales this month" }
    ],
    model: "auto",
  }),
});

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

Rate Limiting per Tier

When you exceed the limit, you receive a 429 Too Many Requests response with a Retry-After header.

Error Codes

| 503 | AI provider temporarily unavailable |