Kreyato Labs - API Documentation

API Documentation

Integrate Kreyato Labs AI into your applications using the REST API.

Authentication
Chat API
Streaming (SSE)
Sessions & Conversation Memory
Error Handling
Code Examples

Authentication

All API requests require an API key. You can create API keys from the Admin Panel under the "API Keys" section.

Pass your API key using either method:

Option 1: X-API-Key Header (Recommended)

X-API-Key: kl_your_api_key_here

Option 2: Authorization Bearer

Authorization: Bearer kl_your_api_key_here

Important: API keys are shown only once when created. Store your key securely and never expose it in client-side code.

Chat API

POST /api/v1/chat

Send a message to the AI assistant and receive a response.

Request Headers

Header	Value
`Content-Type`	`application/json`	Required
`X-API-Key`	Your API key	Required

Request Body

Field	Type	Description
`message`	string	The message to send to the assistant	Required
`session`	string	Session ID for conversation memory. Messages within the same session share context.	Optional
`stream`	boolean	Set to `true` to receive the response as a Server-Sent Events stream	Optional

Standard Response

{
  "response": "The AI assistant's reply text...",
  "session": "api-1"
}

Streaming (SSE)

When stream: true is set, the response is delivered as Server-Sent Events. This allows you to display the response as it's being generated, providing a real-time typing experience.

SSE Event Format

Each event is a JSON object on a data: line. There are three event types:

Delta (partial response chunk)

data: {"type": "delta", "text": "chunk of text"}

Done (stream complete)

data: {"type": "done"}

Error

data: {"type": "error", "error": "error message"}

Sessions & Conversation Memory

By default, each API key gets a single conversation thread. To maintain multiple separate conversations, pass a unique session identifier with each request.

How Sessions Work

Messages within the same session share conversation history
Different session IDs create isolated conversations
If no session is provided, a default session is used per API key
Session IDs can be any string (e.g. "user-123", "ticket-456", "chat-room-a")

Error Handling

Status	Meaning	Example
`400`	Bad Request	Missing `message` field
`401`	Unauthorized	Missing, invalid, or disabled API key
`500`	Server Error	Gateway unavailable or timeout

Error Response Format

{
  "error": "Description of what went wrong"
}

Code Examples

cURL - Simple Request

curl -X POST YOUR_APP_URL/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: kl_your_key_here" \
  -d '{"message": "What is machine learning?"}'

cURL - With Session

# First message
curl -X POST YOUR_APP_URL/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: kl_your_key_here" \
  -d '{"message": "My name is Alex", "session": "user-123"}'

# Follow-up (assistant remembers the context)
curl -X POST YOUR_APP_URL/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: kl_your_key_here" \
  -d '{"message": "What is my name?", "session": "user-123"}'

Python

import requests

API_URL = "YOUR_APP_URL/api/v1/chat"
API_KEY = "kl_your_key_here"

def chat(message, session=None):
    payload = {"message": message}
    if session:
        payload["session"] = session

    response = requests.post(
        API_URL,
        json=payload,
        headers={"X-API-Key": API_KEY}
    )
    response.raise_for_status()
    return response.json()["response"]

# Usage
reply = chat("Explain quantum computing in simple terms")
print(reply)

Python - Streaming

import requests
import json

API_URL = "YOUR_APP_URL/api/v1/chat"
API_KEY = "kl_your_key_here"

def chat_stream(message, session=None):
    payload = {"message": message, "stream": True}
    if session:
        payload["session"] = session

    response = requests.post(
        API_URL,
        json=payload,
        headers={"X-API-Key": API_KEY},
        stream=True
    )
    response.raise_for_status()

    for line in response.iter_lines():
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                data = json.loads(line[6:])
                if data["type"] == "delta":
                    print(data["text"], end="", flush=True)
                elif data["type"] == "done":
                    print()
                    break

# Usage
chat_stream("Write a short poem about coding")

JavaScript / Node.js

const API_URL = "YOUR_APP_URL/api/v1/chat";
const API_KEY = "kl_your_key_here";

async function chat(message, session) {
  const res = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({ message, session }),
  });

  if (!res.ok) throw new Error(await res.text());
  const data = await res.json();
  return data.response;
}

// Usage
const reply = await chat("What is the capital of France?");
console.log(reply);

JavaScript - Streaming

async function chatStream(message, session) {
  const res = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({ message, session, stream: true }),
  });

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let fullText = "";

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

    const chunk = decoder.decode(value);
    for (const line of chunk.split("\n")) {
      if (line.startsWith("data: ")) {
        const data = JSON.parse(line.slice(6));
        if (data.type === "delta") {
          fullText += data.text;
          process.stdout.write(data.text);
        }
        if (data.type === "done") {
          console.log();
          return fullText;
        }
      }
    }
  }
}

// Usage
await chatStream("Tell me a joke");

Rate Limits: There are currently no enforced rate limits, but please be considerate with usage. Each streaming connection holds a WebSocket to the AI gateway for up to 120 seconds.

Kreyato Labs API