Overview
API Overview
Introduction to the Docimal API v2 — structured errors, SSE streaming, and cursor-based pagination.
Introduction
The Docimal API v2 is a RESTful API that lets you build powerful integrations with the Docimal platform. It provides endpoints for managing documents, knowledge bases, workspaces, users, chat sessions, integrations, and webhooks. All endpoints return JSON and use standard HTTP methods.
Base URL
All API requests are made to your Docimal instance base URL. For cloud-hosted accounts, the Agent Service base URL is https://api.docimal.site/agents/api/v1. For self-hosted deployments, replace with your custom domain. All requests must use HTTPS.
API Versioning
The API is versioned through the URL path (/v2/). The current version is v2, which introduces structured error responses, Server-Sent Events (SSE) for streaming, and cursor-based pagination. The legacy v1 endpoints remain available but are deprecated and will be removed in a future release.
Request Format
Send request bodies as JSON with Content-Type: application/json. File uploads use multipart/form-data. All string parameters should be UTF-8 encoded. Date parameters use ISO 8601 format. UUIDs are used for all resource identifiers.
Pagination
List endpoints return paginated results using cursor-based pagination. Responses include a "data" array, "hasMore" boolean, and "nextCursor" string. Pass the cursor as a query parameter to fetch the next page. Default page size is 20 items, configurable up to 100 with the "limit" parameter.
Rate Limiting
API requests are rate-limited per API key. Limits vary by plan: Free (60/min), Starter (300/min), Professional (1000/min), Enterprise (custom). Rate limit information is returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding the limit returns HTTP 429.
Error Handling
Errors return a structured JSON response with fields: status (HTTP status code), error (error type string), message (human-readable description), and details (optional array of field-level errors). Common status codes: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Unprocessable Entity), 429 (Too Many Requests), 500 (Internal Server Error).