Tasks
The tasks feature defines intent-level provider work requests before execution enters the queue. It gives you explicit orchestration control so inbox operations can be created, inspected, and triggered deterministically.
Why This Matters
This feature separates business intent from queue execution details by making the task record the source of truth for requested work. It supports explicit triggering and auditability before job fan-out, which keeps operator control clear when automation needs intervention.
Core Flow
A client creates a task with type, target, and payload, then uses that record as the canonical intent for execution. When triggered, queue jobs are created from the task and subsequent reads reflect task state and linked job outcomes.
Operations
| Operation | Endpoint | Purpose |
|---|---|---|
| Create task | POST /api/accounts/:account_id/tasks | Register new account-scoped task intent |
| List tasks | GET /api/accounts/:account_id/tasks | Fetch task timeline for account |
| Search tasks | POST /api/accounts/:account_id/tasks/search | Query tasks by type/state filters |
| Get task | GET /api/tasks/:task_id | Retrieve one task |
| Update task | PATCH /api/tasks/:task_id | Modify mutable task fields |
| Delete task | DELETE /api/tasks/:task_id | Remove task |
| Trigger task | POST /api/tasks/:task_id/trigger | Start or restart execution from task |
Key Data and State
{
id: "tsk_...",
account_id: "acc_...",
task_type: "imap_sync_messages",
target_credential_id: "pc_...",
payload: { folder: "INBOX" },
priority: 0
}Failure Modes and Controls
Invalid task payloads or target references are rejected before queue execution begins. Trigger actions are explicit and task-scoped, account access checks apply to create/read/mutate boundaries, and task deletion does not happen as a side effect of unrelated job cleanup.