Chat API

AI conversation with tool calling support.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/chat	Get message history
POST	/api/agents/{id}/chat	Send message
DELETE	/api/agents/{id}/chat	Clear history

Get Messages

GET /api/agents/{id}/chat?limit=50&conversation_id=conv-123

Query Parameters

Parameter	Type	Description
limit	number	Max messages (default: 50)
conversation_id	string	Filter by conversation
before	number	Messages before ID
after	number	Messages after ID

Response

{
  "messages": [
    {
      "id": 1,
      "role": "user",
      "content": "Hello!",
      "created_at": "2024-12-15T10:00:00Z"
    },
    {
      "id": 2,
      "role": "assistant",
      "content": "Hi there! How can I help you?",
      "created_at": "2024-12-15T10:00:01Z"
    }
  ],
  "meta": {
    "total": 100,
    "has_more": true
  }
}

Send Message

POST /api/agents/{id}/chat
Content-Type: application/json

Request Body

{
  "message": "What's the weather like?",
  "conversation_id": "conv-123"
}

Response

{
  "id": 3,
  "role": "assistant",
  "content": "I don't have access to weather information...",
  "conversation_id": "conv-123",
  "created_at": "2024-12-15T10:01:00Z"
}

With Tool Calls

{
  "id": 3,
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_123",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"location\": \"Tokyo\"}"
      }
    }
  ]
}

Clear History

DELETE /api/agents/{id}/chat

Query Parameters

Parameter	Type	Description
conversation_id	string	Clear specific conversation

Response

{
  "success": true,
  "deleted": 150
}

Message Roles

Role	Description
user	User message
assistant	AI response
system	System instruction
tool	Tool result

Message Format

User Message

{
  "id": 1,
  "role": "user",
  "content": "Hello!",
  "metadata": {
    "source": "web"
  }
}

Assistant Message

{
  "id": 2,
  "role": "assistant",
  "content": "Hi there!",
  "tool_calls": null
}

Tool Call

{
  "id": 3,
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_123",
      "type": "function",
      "function": {
        "name": "search_database",
        "arguments": "{\"query\": \"recent orders\"}"
      }
    }
  ]
}

Tool Result

{
  "id": 4,
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"results\": [...]}"
}

Streaming

For real-time responses:

POST /api/agents/{id}/chat
Content-Type: application/json

{
  "message": "Tell me a story",
  "stream": true
}

SSE Response

data: {"type": "start", "id": 5}

data: {"type": "delta", "content": "Once"}

data: {"type": "delta", "content": " upon"}

data: {"type": "delta", "content": " a time"}

data: {"type": "done", "message": {...}}

Context Management

Set Context

POST /api/agents/{id}/chat
Content-Type: application/json

{
  "message": "Hello",
  "context": {
    "user": {
      "name": "John",
      "plan": "premium"
    }
  }
}

System Prompt Override

{
  "message": "Hello",
  "system_prompt": "You are a technical support agent."
}

Conversation Threading

Start New Conversation

Omit conversation_id:

{
  "message": "Hello"
}

Response includes new conversation_id:

{
  "id": 1,
  "conversation_id": "conv-new-123",
  "content": "Hi!"
}

Continue Conversation

Include conversation_id:

{
  "message": "Follow-up question",
  "conversation_id": "conv-123"
}

Errors

Code	Description
400	Invalid message
429	Rate limited
500	AI service error

Examples

Simple Chat

curl -X POST https://your-domain.com/api/agents/{id}/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'

With Context

curl -X POST https://your-domain.com/api/agents/{id}/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is my order status?",
    "context": {
      "customer_id": "cust-123",
      "order_id": "order-456"
    }
  }'

Streaming Response

const response = await fetch('/api/agents/{id}/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Tell me a story',
    stream: true
  })
})

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 = JSON.parse(line.slice(6))
      if (data.type === 'delta') {
        process.stdout.write(data.content)
      }
    }
  }
}