Common Patterns
Documentation for Common Patterns
Pagination
List endpoints accept the following query parameters:
| Parameter | Type | Default | Constraints | Description |
|---|---|---|---|---|
page | number | 1 | min: 1 | Page number (1-indexed) |
limit | number | 20 | min: 1, max: 100 | Items per page |
Paginated responses include a pagination object:
Error Responses
All errors follow a consistent JSON shape:
Common HTTP Status Codes
| Status | Meaning |
|---|---|
200 OK | Success |
201 Created | Resource successfully created |
400 Bad Request | Invalid request parameters or body (validation failure) |
401 Unauthorized | Missing or invalid JWT token |
403 Forbidden | Token valid but permission denied |
404 Not Found | Resource not found or not accessible (ownership check failed) |
429 Too Many Requests | Rate limit exceeded |
500 Internal Server Error | Unexpected server error |
503 Service Unavailable | Server is draining for deployment; retry after Retry-After seconds |
Note: The server uses 404 to mask forbidden resources (for security). If you receive 404, the resource may exist but you don't have access.
Server-Sent Events (SSE)
Several endpoints stream responses using Server-Sent Events (SSE). These are long-lived HTTP connections that push events incrementally.
Response Headers
Event Format
Each event has an event name and a JSON-encoded data payload:
SSE Event Types
Chat / Rules streaming (POST /chats/:threadId/messages, POST /rules/:threadId/messages)
| Event | Description |
|---|---|
ping | Keep-alive heartbeat, sent every 9 seconds |
message | AI assistant text chunk: { "content": "<text>" } |
error | Stream error: { "content": "<message>" } |
Workflow execution streaming (POST /workflow-runs/execute/stream)
| Event | Description |
|---|---|
ping | Keep-alive heartbeat, sent every 9 seconds |
activity-run | Activity run status update: { "content": { "workflowRunId": "...", "status": "...", ... } } |
workflow-run | Workflow run status update: { "content": { "workflowRunId": "...", "status": "...", ... } } |
thinking | AI thinking trace: { "content": "<thinking text>", "stepId": "...", "activityRunId": "..." } |
result | Final result when workflow completes: { "success": true, "workflowRun": { ... } } |
error | Execution error: { "error": "...", "details": "..." } |
Connecting to an SSE Endpoint
Handling Deployment Draining
When the server is restarting for deployment, SSE-enabled endpoints return 503 Service Unavailable before establishing the stream:
Form Data (Multipart)
Several endpoints accept multipart/form-data requests, especially those involving file uploads or AI message sending.
Encoding Complex Fields
JSON objects and arrays within form data are JSON-encoded strings:
IDs and UUIDs
All public resource IDs use UUIDv7 format (time-sortable), e.g.:
018f4e3a-1234-7abc-8def-0123456789ab
Internal IDs (bigint) are never exposed in API responses.
Timestamps
All timestamps are returned as ISO 8601 strings:
"2024-01-15T10:30:00.000Z"
Search
List endpoints that support search perform case-insensitive substring matching on the resource name field.