API Documentation

Quick Start

1. Create a Conversation

POST /api/conversations

{
  "agent_id": 1,
  "user_id": null
}

2. Send a Message

POST /api/chat

{
  "conversation_id": 1,
  "message": "Hello, I need help scheduling a meeting"
}

3. Response

{
  "message": {
    "id": 42,
    "role": "assistant",
    "content": "I'd be happy to help you schedule a meeting...",
    "model": "claude-3-5-sonnet-20241022",
    "tokens_input": 45,
    "tokens_output": 128,
    "latency_ms": 342
  },
  "conversation": {
    "id": 1,
    "message_count": 2,
    "total_tokens": 173
  }
}

Agents

Agents are AI assistants with customized personalities, capabilities, and knowledge bases.

Field	Type	Description
name	string	Display name of the agent
system_prompt	text	Instructions that define agent behavior
model	string	AI model to use (claude-3-5-sonnet, gpt-4, etc.)
tools	array	List of tools/functions agent can call
temperature	decimal	Creativity level (0.0 - 1.0)

Streaming Responses

For real-time token streaming, use Server-Sent Events:

GET /api/chat/stream?conversation_id=1&message=Hello

// Response is a stream of SSE events:
data: {"token": "I"}
data: {"token": "'d"}
data: {"token": " be"}
data: {"token": " happy"}
data: {"token": " to"}
data: {"token": " help"}
data: {"token": "..."}
data: [DONE]

Tool Calling

Agents can execute functions to integrate with external systems:

Define Tools

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with participants",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "date": { "type": "string", "format": "date-time" },
      "participants": { "type": "array" }
    }
  }
}

Tool Call Response

{
  "message": {
    "role": "assistant",
    "content": "I'll schedule that meeting for you.",
    "tool_calls": [{
      "id": "call_abc123",
      "function": "schedule_meeting",
      "arguments": {
        "title": "Project Review",
        "date": "2026-01-25T14:00:00Z",
        "participants": ["john@example.com"]
      }
    }]
  }
}

Document Retrieval (RAG)

Upload documents to create a knowledge base for your agents:

Upload Document

POST /api/documents

Content-Type: multipart/form-data
file: [PDF/TXT/DOCX file]
agent_id: 1

How It Works

Documents are parsed and split into chunks
Chunks are embedded using a vector embedding model
Embeddings are stored in a vector database (Pinecone/FAISS)
When a user asks a question, relevant chunks are retrieved
Retrieved context is included in the AI prompt