API v1 Reference
Chat API (v1)
API v1 reference for managing chat sessions and sending messages to your Docimal AI agent.
Overview
The Chat API v1 provides endpoints for starting chat sessions, sending messages, and receiving AI responses. This is the original API — for new integrations, consider using API v2 which offers structured errors, SSE streaming, and cursor-based pagination.
Start a Chat Session
POST /chat/start — Initialize a new chat session. Required body: { chatbotId: string }. Optional: { userId: string, metadata: object }. Returns: { sessionId: string, messages: Message[] } with the welcome message(s) configured in your workflow.
Send a Message
POST /chat/{sessionId}/message — Send a user message and receive the AI response. Body: { content: string }. Returns the assistant's response message. For streaming responses, use the SSE endpoint at GET /chat/{sessionId}/stream which pushes updates as the AI generates tokens.
Get Session Info
GET /chat/{sessionId} — Retrieve session details including status, message count, creation time, and last activity. Use this to check if a session is still active before sending messages.
End a Session
POST /chat/{sessionId}/end — Explicitly end a chat session and trigger the conversation_end workflow. Sessions also time out automatically after a period of inactivity, triggering the timeout workflow.