Task Orchestration
The task system manages the full lifecycle of user-submitted work requests — from creation through agent dispatch to paid result delivery. Tasks bridge the gap between user intent and AI agent execution.Overview
Task Lifecycle
Every task progresses through a defined state machine:Task States
| State | Description |
|---|---|
PENDING | Task created, not yet submitted for processing |
RUNNING | Submitted to agent engine, awaiting result |
COMPLETED | Agent returned a result, available for viewing |
FAILED | Agent processing encountered an error |
CANCELLED | Task deleted by user before completion |
Payment States
| State | Description |
|---|---|
UNPAID | Result available but not yet purchased |
PAID | User paid credits to unlock full result |
REFUNDED | Payment reversed |
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/task/create | Create a new task |
POST | /api/task/submit | Submit task to agent for processing |
POST | /api/task/list | List user’s tasks with pagination |
POST | /api/task/result | Get task result (preview or full) |
POST | /api/task/pay | Pay credits to unlock full result |
POST | /api/task/rename | Rename a task |
POST | /api/task/pin | Pin/unpin a task |
POST | /api/task/delete | Delete (cancel) a task |
Agent Dispatch
When a task is submitted, the Core API dispatches it to the configured agent engine.Configuration
| Environment Variable | Description |
|---|---|
AGENT_INVOKE_URL | URL of the agent engine’s task intake endpoint |
AGENT_INVOKE_URL is not configured, the system enters test mode — tasks complete immediately with mock data, useful for development and testing.
Agent Callback
The agent engine reports results asynchronously via:Pay-to-View Model
Task results use a two-tier visibility model:| Access Level | Content | Auth Required |
|---|---|---|
| Preview | resultPreview — summary or truncated result | JWT (task owner) |
| Full | resultFull — complete result data | JWT + PAID status |
Task Management
Beyond the core lifecycle, users can organize their tasks:| Action | Endpoint | Description |
|---|---|---|
| Rename | POST /api/task/rename | Change task display name |
| Pin | POST /api/task/pin | Pin/unpin for quick access |
| Delete | POST /api/task/delete | Cancel and remove a pending task |
| List | POST /api/task/list | Paginated list with filters |
File Attachments
Tasks can reference files stored in S3. The file service provides:| Method | Endpoint | Description |
|---|---|---|
POST | /api/file/upload | Upload file to S3 |
GET | /api/file/download/:fileUuid | Download a file |
DELETE | /api/file/:fileUuid | Delete a file |
Related Pages
Finance & Payments
Credit consumption powers the pay-to-view model
Agent Platform
Profy agents process submitted tasks