Agent Chat API

POST /api/v1/agents/{agent_id}/chat

{
  "message": "What are your business hours?",
  "conversation_id": "conv-123",
  "file_urls": [
    {
      "asset_id": "asset-456",
      "url": "https://your-domain.com/api/v1/upload/files/general/2026/09/7f3a1c9d2b10_a1b2c3d4.pdf",
      "filename": "7f3a1c9d2b10_a1b2c3d4.pdf",
      "size": 1048576,
      "mime_type": "application/pdf"
    }
  ],
  "variables": {
    "customer_tier": "premium"
  }
}

curl -X POST "https://your-domain.com/api/v1/agents/agent-123/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "conversation_id": "conv-123"
  }'

{
  "code": 0,
  "data": {
    "conversation_id": "conv-123",
    "message": {
      "id": "msg-456",
      "conversation_id": "conv-123",
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "tool_calls": [],
      "tool_name": null,
      "model_used": "gpt-4",
      "token_usage": {
        "prompt": 150,
        "completion": 25,
        "total": 175
      },
      "duration_ms": 2300,
      "rag_context": [
        {
          "document_id": "doc-789",
          "document_name": "Business Hours Policy",
          "chunk_id": "chunk-012",
          "content": "Business hours: Monday-Friday, 9 AM to 5 PM EST",
          "score": 0.95,
          "citation_id": "rag_0123456789abcdef"
        }
      ],
      "created_at": "2026-02-11T16:00:00Z",
      "version_number": 1,
      "version_count": 1
    },
    "usage": {
      "prompt": 150,
      "completion": 25,
      "total": 175
    }
  },
  "msg": "success"
}

event: message_start
data: {"conversation_id": "conv-123", "message_id": "msg-456"}

event: content_delta
data: {"delta": "Our"}

event: content_delta
data: {"delta": " business"}

event: content_delta
data: {"delta": " hours"}

event: rag_context
data: {"contexts": [{"document_name": "FAQ", "content": "...", "score": 0.95}]}

event: message_end
data: {"usage": {"prompt_tokens": 150, "completion_tokens": 25, "total_tokens": 175}, "timing": {"first_token_ms": 320, "duration_ms": 2300, "tokens_per_second": 10.9}}

event: media_result
data: {"kind":"media.image","success":true,"images":[{"image":{"url":"/api/v1/upload/files/generated-images/2026/09/9a8b7c6d5e4f_55667788.png","asset_ref":"a1b2","format":"png"}}]}

POST /api/v1/agents/{agent_id}/chat/runs

{
  "code": 0,
  "data": {
    "run_id": "8f3b1c9d-2b10-4a1b-9c3d-7f3a1c9d2b10",
    "conversation_id": "conv-123",
    "user_message_id": "msg-456",
    "status": "queued",
    "stream_url": "/agents/agent-123/chat/runs/8f3b1c9d-2b10-4a1b-9c3d-7f3a1c9d2b10/stream"
  },
  "msg": "success"
}

GET /api/v1/agents/{agent_id}/chat/runs/{run_id}/stream?after_sequence=N

POST /api/v1/agents/{agent_id}/chat/runs/{run_id}/stop

POST /api/v1/agents/{agent_id}/chat/runs/{run_id}/answers

{
  "tool_call_id": "call-123",
  "answers": {
    "deployment_target": "cloud"
  },
  "skipped": false
}

POST /api/v1/agents/{agent_id}/messages/{message_id}/regenerate

{
  "variables": {}
}

curl -X POST "https://your-domain.com/api/v1/agents/agent-123/messages/msg-002/regenerate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {}
  }'

{
  "code": 0,
  "data": {
    "conversation_id": "conv-123",
    "message": {
      "id": "msg-003",
      "conversation_id": "conv-123",
      "role": "assistant",
      "content": "Our business hours are Monday through Friday, from 9:00 AM to 5:00 PM Eastern Standard Time.",
      "token_usage": {
        "total": 180
      },
      "created_at": "2026-02-11T16:15:00Z",
      "version_number": 2,
      "version_count": 2
    },
    "usage": {
      "total": 180
    }
  },
  "msg": "success"
}

POST /api/v1/agents/{agent_id}/messages/{message_id}/edit/stream

{"content": "What are your holiday hours?"}

GET /api/v1/agents/{agent_id}/messages/{message_id}/versions

POST /api/v1/agents/{agent_id}/messages/{message_id}/switch-version

{"version_id": "msg-version-003"}

GET /api/v1/conversations

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "conv-123",
        "agent_id": "agent-456",
        "agent_name": "Customer Support Agent",
        "agent_icon": "🤖",
        "title": "Business Hours Inquiry",
        "message_count": 5,
        "created_at": "2026-02-11T16:00:00Z",
        "updated_at": "2026-02-11T16:05:00Z",
        "user_id": "user-123",
        "user_name": "alice"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

GET /api/v1/conversations/{conversation_id}

{
  "code": 0,
  "data": {
    "id": "conv-123",
    "agent_id": "agent-456",
    "agent_name": "Customer Support Agent",
    "agent_icon": "🤖",
    "title": "Business Hours Inquiry",
    "variables": {},
    "message_count": 5,
    "token_usage": 875,
    "created_at": "2026-02-11T16:00:00Z",
    "updated_at": "2026-02-11T16:05:00Z",
    "messages": [
      {
        "id": "msg-001",
        "conversation_id": "conv-123",
        "role": "user",
        "content": "What are your business hours?",
        "created_at": "2026-02-11T16:00:00Z",
        "version_number": 1,
        "version_count": 1
      },
      {
        "id": "msg-002",
        "conversation_id": "conv-123",
        "role": "assistant",
        "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
        "tool_calls": [],
        "rag_context": [
          {
            "document_id": "doc-789",
            "document_name": "Business Hours Policy",
            "score": 0.95
          }
        ],
        "created_at": "2026-02-11T16:00:02Z",
        "version_number": 1,
        "version_count": 1
      }
    ]
  },
  "msg": "success"
}

PATCH /api/v1/agents/conversations/{conversation_id}

{
  "title": "Updated Conversation Title"
}

{
  "code": 0,
  "data": {
    "id": "conv-123",
    "title": "Updated Conversation Title",
    "updated_at": "2026-02-11T16:10:00Z"
  },
  "msg": "Conversation updated successfully"
}

DELETE /api/v1/conversations/{conversation_id}

{
  "code": 0,
  "data": {
    "id": "conv-123"
  },
  "msg": "Conversation deleted successfully"
}

DELETE /api/v1/conversations?ids=conv-123&ids=conv-456

curl -X DELETE "https://your-domain.com/api/v1/conversations?ids=conv-123&ids=conv-456" \
  -H "Authorization: Bearer YOUR_TOKEN"

DELETE /api/v1/agents/conversations/{conversation_id}/messages/{message_id}

import requests

def chat_with_agent(agent_id, message, conversation_id=None):
    """Send message to agent."""
    url = f"https://your-domain.com/api/v1/agents/{agent_id}/chat"
    headers = {
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    }
    data = {
        "message": message,
        "conversation_id": conversation_id
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    if result['code'] == 0:
        return result['data']
    else:
        raise Exception(f"Error: {result['msg']}")

# Usage
response = chat_with_agent(
    agent_id="agent-123",
    message="What are your business hours?",
    conversation_id="conv-123"
)

print(f"Response: {response['message']['content']}")
print(f"Conversation ID: {response['conversation_id']}")

async function chatWithAgent(agentId, message, conversationId = null) {
  const url = `https://your-domain.com/api/v1/agents/${agentId}/chat`;

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: message,
      conversation_id: conversationId,
    }),
  });

  const result = await response.json();

  if (result.code === 0) {
    return result.data;
  } else {
    throw new Error(result.msg);
  }
}

// Usage
const response = await chatWithAgent(
  'agent-123',
  'What are your business hours?',
  'conv-123'
);

console.log('Response:', response.message.content);
console.log('Conversation ID:', response.conversation_id);