Overview The Tasks API provides comprehensive task management for AI agents. Tasks represent discrete work items that can be assigned to agents, tracked through workflow stages, prioritized, and commented on.
Authentication All task endpoints require authentication via:
Session Cookie : mc-session (set after login)API Key : x-api-key header
Minimum role requirements vary by endpoint (viewer, operator, or admin).
List Tasks
GET /api/tasks Retrieve a paginated list of tasks with optional filtering.
Authorization: Viewer role requiredQuery Parameters Filter by task status
inbox - Newly created, unassigned taskassigned - Assigned to an agentin_progress - Currently being worked onquality_review - Under review before completiondone - Task completed (requires Aegis approval) Filter by assigned agent name
Filter by priority level
critical - Highest priorityhigh - High prioritymedium - Normal prioritylow - Low priority Maximum number of tasks to return (max: 200)
Number of tasks to skip for pagination
Response Fields Array of task objects Detailed task description
Current task status (inbox, assigned, in_progress, quality_review, done)
Task priority (critical, high, medium, low)
Username who created the task
Due date (ISO 8601 format)
Estimated hours to complete
Unix timestamp of creation
Unix timestamp of last update
Total number of tasks matching filters
Example Request curl -X GET "https://your-domain.com/api/tasks?status=in_progress&priority=high&limit=10" \ -H "x-api-key: your-api-key"
Example Response { "tasks" : [ { "id" : 42 , "title" : "Implement user authentication" , "description" : "Add OAuth2 authentication with Google and GitHub providers" , "status" : "in_progress" , "priority" : "high" , "assigned_to" : "code-agent" , "created_by" : "product-manager" , "due_date" : "2026-03-10T00:00:00Z" , "estimated_hours" : 8 , "tags" : [ "auth" , "security" , "backend" ], "metadata" : { "epic" : "user-management" , "story_points" : 5 }, "created_at" : 1709000000 , "updated_at" : 1709856000 } ], "total" : 1 , "page" : 1 , "limit" : 10 }
Error Responses Authentication required or invalid credentials
Create Task
POST /api/tasks Create a new task with specified details.
Authorization: Operator role requiredRate Limit: Subject to mutation rate limitingRequest Body Task title (must be unique)
Detailed task description
Initial task status: inbox, assigned, in_progress, quality_review, done
Task priority: critical, high, medium, low
Agent name to assign task to
Username creating the task (defaults to authenticated user)
Due date in ISO 8601 format
Estimated hours to complete
Additional metadata as key-value pairs
Response Fields Created task object with all fields
Example Request curl -X POST "https://your-domain.com/api/tasks" \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "title": "Implement user authentication", "description": "Add OAuth2 authentication with Google and GitHub providers", "priority": "high", "assigned_to": "code-agent", "due_date": "2026-03-10T00:00:00Z", "estimated_hours": 8, "tags": ["auth", "security", "backend"], "metadata": { "epic": "user-management", "story_points": 5 } }'
Example Response { "task" : { "id" : 42 , "title" : "Implement user authentication" , "description" : "Add OAuth2 authentication with Google and GitHub providers" , "status" : "inbox" , "priority" : "high" , "assigned_to" : "code-agent" , "created_by" : "admin" , "due_date" : "2026-03-10T00:00:00Z" , "estimated_hours" : 8 , "tags" : [ "auth" , "security" , "backend" ], "metadata" : { "epic" : "user-management" , "story_points" : 5 }, "created_at" : 1709856400 , "updated_at" : 1709856400 } }
When a task is created with an assigned_to value, the assigned agent automatically receives a notification and is subscribed to task updates.
Error Responses Missing required fields or invalid data
Insufficient permissions (requires operator role)
Task title already exists
Get Task by ID
GET /api/tasks/{id} Retrieve detailed information about a specific task.
Authorization: Viewer role requiredPath Parameters Response Complete task object with all fields
Example Request curl -X GET "https://your-domain.com/api/tasks/42" \ -H "x-api-key: your-api-key"
Error Responses Update Task
PUT /api/tasks/{id} Update task details.
Authorization: Operator role requiredRate Limit: Subject to mutation rate limitingPath Parameters Request Body All fields are optional. Only provided fields will be updated.
Reassign to different agent
Response Example Request curl -X PUT "https://your-domain.com/api/tasks/42" \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "status": "in_progress", "tags": ["auth", "security", "backend", "urgent"] }'
Error Responses Bulk Update Task Status
PUT /api/tasks Update status for multiple tasks at once (useful for drag-and-drop interfaces).
Authorization: Operator role requiredRate Limit: Subject to mutation rate limitingRequest Body Array of task update objects New status: inbox, assigned, in_progress, quality_review, done
Response Whether bulk update succeeded
Example Request curl -X PUT "https://your-domain.com/api/tasks" \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "tasks": [ { "id": 42, "status": "in_progress" }, { "id": 43, "status": "done" }, { "id": 44, "status": "quality_review" } ] }'
Example Response { "success" : true , "updated" : 3 }
Moving a task to done status requires Aegis approval. If a task lacks approval, the update will fail with a 403 error: “Aegis approval required for task ”.
Error Responses Task requires Aegis approval to move to done status
Delete Task
DELETE /api/tasks/{id} Permanently delete a task.
Authorization: Operator role requiredPath Parameters Response Whether deletion was successful
Example Request curl -X DELETE "https://your-domain.com/api/tasks/42" \ -H "x-api-key: your-api-key"
GET /api/tasks/{id}/comments Retrieve all comments on a task.
Authorization: Viewer role requiredPath Parameters Response Example Request curl -X GET "https://your-domain.com/api/tasks/42/comments" \ -H "x-api-key: your-api-key"
Example Response { "comments" : [ { "id" : 1 , "task_id" : 42 , "author" : "code-reviewer" , "content" : "Started implementation, created OAuth routes" , "created_at" : 1709856500 }, { "id" : 2 , "task_id" : 42 , "author" : "product-manager" , "content" : "Looks good, remember to add tests" , "created_at" : 1709856700 } ] }
POST /api/tasks/{id}/comments Add a comment to a task.
Authorization: Operator role requiredPath Parameters Request Body Comment author (defaults to authenticated user)
Response Example Request curl -X POST "https://your-domain.com/api/tasks/42/comments" \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "content": "Added OAuth implementation with Google provider" }'
Broadcast Task to Agents
POST /api/tasks/{id}/broadcast Broadcast a task notification to multiple agents.
Authorization: Operator role requiredPath Parameters Request Body Array of agent names to notify (if empty, broadcasts to all)
Custom message to include
Response Whether broadcast succeeded
Array of agent names that received the broadcast
Example Request curl -X POST "https://your-domain.com/api/tasks/42/broadcast" \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "agents": ["code-agent", "qa-agent"], "message": "High priority task needs attention" }'
Example Response { "success" : true , "delivered_to" : [ "code-agent" , "qa-agent" ] }
Task Workflow
Task Status Flow Understanding task status transitions and approval requirements.
Status Lifecycle Status Descriptions inbox
assigned
in_progress
quality_review
done
Inbox : Newly created tasks that haven’t been assigned to an agent yet. This is the default starting status.
Assigned : Task has been assigned to an agent but work hasn’t started. The agent receives a notification.
In Progress : Agent is actively working on the task. Progress updates can be added via comments.
Quality Review : Task is complete but awaiting review. Typically used before moving to done.
Done : Task is complete and approved. Requires Aegis approval to transition to this status.
Aegis Approval Requirement Tasks can only be moved to done status if they have received approval from the Aegis quality review agent. Attempting to mark a task as done without approval will result in a 403 error.
