Tasks API - Mission Control

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 required

Query Parameters

string

Filter by task status

Show Allowed values

inbox - Newly created, unassigned task
assigned - Assigned to an agent
in_progress - Currently being worked on
quality_review - Under review before completion
done - Task completed (requires Aegis approval)

string

Filter by assigned agent name

string

Filter by priority level

Show Allowed values

critical - Highest priority
high - High priority
medium - Normal priority
low - Low priority

integer

default:"50"

Maximum number of tasks to return (max: 200)

integer

default:"0"

Number of tasks to skip for pagination

Response Fields

array

Array of task objects

Show Task Object

integer

Unique task identifier

string

Task title

string

Detailed task description

string

Current task status (inbox, assigned, in_progress, quality_review, done)

string

Task priority (critical, high, medium, low)

string

Name of assigned agent

string

Username who created the task

string

Due date (ISO 8601 format)

number

Estimated hours to complete

array

Array of tag strings

object

Additional metadata

integer

Unix timestamp of creation

integer

Unix timestamp of last update

integer

Total number of tasks matching filters

integer

Current page number

integer

Number of tasks per page

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"

const response = await fetch('/api/tasks?status=in_progress&priority=high&limit=10', {
  headers: {
    'x-api-key': 'your-api-key'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://your-domain.com/api/tasks',
    params={'status': 'in_progress', 'priority': 'high', 'limit': 10},
    headers={'x-api-key': 'your-api-key'}
)
tasks = response.json()

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 required Rate Limit: Subject to mutation rate limiting

Request Body

string

required

Task title (must be unique)

string

Detailed task description

string

default:"inbox"

Initial task status: inbox, assigned, in_progress, quality_review, done

string

default:"medium"

Task priority: critical, high, medium, low

string

Agent name to assign task to

string

Username creating the task (defaults to authenticated user)

string

Due date in ISO 8601 format

number

Estimated hours to complete

array

Array of tag strings

object

Additional metadata as key-value pairs

Response Fields

object

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
    }
  }'

const response = await fetch('/api/tasks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    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
    }
  })
});
const data = await response.json();

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

Authentication required

Insufficient permissions (requires operator role)

Task title already exists

Rate limit exceeded

Get Task by ID

GET /api/tasks/{id}

Retrieve detailed information about a specific task.

Authorization: Viewer role required

Path Parameters

integer

required

Task ID

Response

object

Complete task object with all fields

Example Request

cURL

curl -X GET "https://your-domain.com/api/tasks/42" \
  -H "x-api-key: your-api-key"

Error Responses

Task does not exist

Update Task

PUT /api/tasks/{id}

Update task details.

Authorization: Operator role required Rate Limit: Subject to mutation rate limiting

Path Parameters

integer

required

Task ID to update

Request Body

All fields are optional. Only provided fields will be updated.

string

New task title

string

Updated description

string

New status

string

Updated priority

string

Reassign to different agent

string

Updated due date

number

Updated estimate

array

Updated tags array

object

Updated metadata

Response

object

Updated task object

Example Request

cURL

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

Task does not exist

Bulk Update Task Status

PUT /api/tasks

Update status for multiple tasks at once (useful for drag-and-drop interfaces).

Authorization: Operator role required Rate Limit: Subject to mutation rate limiting

Request Body

array

required

Array of task update objects

Show Task Update Object

integer

required

Task ID to update

string

required

New status: inbox, assigned, in_progress, quality_review, done

Response

boolean

Whether bulk update succeeded

integer

Number of tasks updated

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" }
    ]
  }'

const response = await fetch('/api/tasks', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    tasks: [
      { id: 42, status: 'in_progress' },
      { id: 43, status: 'done' },
      { id: 44, status: 'quality_review' }
    ]
  })
});
const data = await response.json();

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 required

Path Parameters

integer

required

Task ID to delete

Response

boolean

Whether deletion was successful

Example Request

cURL

curl -X DELETE "https://your-domain.com/api/tasks/42" \
  -H "x-api-key: your-api-key"

List Task Comments

GET /api/tasks/{id}/comments

Retrieve all comments on a task.

Authorization: Viewer role required

Path Parameters

integer

required

Task ID

Response

array

Array of comment objects

Show Comment Object

integer

Comment ID

integer

Task ID

string

Comment author

string

Comment text

integer

Unix timestamp

Example Request

cURL

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
    }
  ]
}

Add Task Comment

POST /api/tasks/{id}/comments

Add a comment to a task.

Authorization: Operator role required

Path Parameters

integer

required

Task ID

Request Body

string

required

Comment text

string

Comment author (defaults to authenticated user)

Response

object

Created comment object

Example Request

cURL

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 required

Path Parameters

integer

required

Task ID to broadcast

Request Body

array

Array of agent names to notify (if empty, broadcasts to all)

string

Custom message to include

Response

boolean

Whether broadcast succeeded

array

Array of agent names that received the broadcast

Example Request

cURL

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.

Aegis Approval RequirementTasks 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.

​Overview

​Authentication

​List Tasks

GET /api/tasks

​Query Parameters

​Response Fields

​Example Request

​Example Response

​Error Responses

​Create Task

POST /api/tasks

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

​Get Task by ID

GET /api/tasks/{id}

​Path Parameters

​Response

​Example Request

​Error Responses

​Update Task

PUT /api/tasks/{id}

​Path Parameters

​Request Body

​Response

​Example Request

​Error Responses

​Bulk Update Task Status

PUT /api/tasks

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Delete Task

DELETE /api/tasks/{id}

​Path Parameters

​Response

​Example Request

​List Task Comments

GET /api/tasks/{id}/comments

​Path Parameters

​Response

​Example Request

​Example Response

​Add Task Comment

POST /api/tasks/{id}/comments

​Path Parameters

​Request Body

​Response

​Example Request

​Broadcast Task to Agents

POST /api/tasks/{id}/broadcast

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Task Workflow

Task Status Flow

​Status Lifecycle

​Status Descriptions

Overview

Authentication

List Tasks

Query Parameters

Response Fields

Example Request

Example Response

Error Responses

Create Task

Request Body

Response Fields

Example Request

Example Response

Error Responses

Get Task by ID

Path Parameters

Response

Example Request

Error Responses

Update Task

Path Parameters

Request Body

Response

Example Request

Error Responses

Bulk Update Task Status

Request Body

Response

Example Request

Example Response

Error Responses

Delete Task

Path Parameters

Response

Example Request

List Task Comments

Path Parameters

Response

Example Request

Example Response

Add Task Comment

Path Parameters

Request Body

Response

Example Request

Broadcast Task to Agents

Path Parameters

Request Body

Response

Example Request

Example Response

Task Workflow

Status Lifecycle

Status Descriptions