Getting Started
REST API Integration
Build custom chat interfaces, mobile apps, or server-to-server integrations using the Docimal REST API.
Overview
The Docimal REST API gives you full programmatic control over chat sessions, agent configuration, documents, and more. Use it to build custom chat UIs, integrate AI conversations into mobile apps, or create server-side automation that interacts with your Docimal agents. The API base URL for the Agent Service is https://api.docimal.site/agents/api/v1.
Authentication
Public chatbot endpoints (starting sessions, sending messages, getting config) use API key authentication via the X-API-Key header. Generate a public API key (prefixed with dcml_pk_) from the Chatbot > Deploy tab. Management endpoints (workspaces, documents, chatbot config) use JWT Bearer tokens in the Authorization header. Tokens are obtained through the login flow and include tenant context.
Chat Sessions
Start a session: POST /public/chatbot/sessions with X-API-Key header. Optionally include visitorId, user info (name, email), and metadata. The response contains a sessionId and welcome message. Send messages: POST /public/chatbot/sessions/{sessionId}/messages with body { message: "..." }. The response includes sessionId, userMessage, assistantMessage, status, metadata (with sources), and createdAt. For streaming: POST /public/chatbot/sessions/{sessionId}/stream returns Server-Sent Events with chunk, start, and end event types.
Chatbot Configuration
Retrieve the public chatbot config: GET /public/chatbot/config with X-API-Key header. The response includes id, name, avatarUrl, welcomeMessage, suggestedQuestions, theme (primaryColor, mode, headerStyle, messageStyle, inputStyle, fontFamily, borderRadius), features (messageFeedback, fileUpload, typingIndicator, showSources, notificationSound), and branding (poweredBy). Use this to build custom chat UIs that match the chatbot branding.
API Key Management
API keys are managed via the authenticated endpoints: POST /workspaces/{workspaceId}/chatbot/api-keys to create (returns the plaintext key once), GET to list (keys are masked), PATCH /{keyId} to update settings, DELETE /{keyId} to revoke. Keys support: name, description, allowedDomains (with wildcard support like *.example.com), rateLimitPerHour (default 1000), rateLimitPerDay (default 10000), environment tag, and expiresAt date.
Error Handling
The API uses standard HTTP status codes: 400 (validation errors), 401 (invalid/expired API key), 403 (domain not allowed), 404 (not found), 429 (rate limit exceeded), 500 (internal error). Error responses include statusCode, message, and error fields. When rate limited (429), implement exponential backoff before retrying.
Rate Limits
Each API key has configurable rate limits: rateLimitPerHour (default 1000) and rateLimitPerDay (default 10000). Rate limiting uses Redis with an in-memory fallback. When limits are exceeded, the API returns HTTP 429. Monitor key usage via GET /workspaces/{workspaceId}/chatbot/api-keys/{keyId}/stats which returns currentHourUsage, currentDayUsage, and percentage indicators.