Tasks API

Tasks represent work items that can be assigned to agents or users. Use the Tasks API to manage workflows, track progress, and coordinate work across your organization.

Base URL: https://cc.teamday.ai/api/v1/tasks

Authentication: Personal Access Token required

Endpoints Overview

MethodEndpointDescriptionStatus
GET/tasksList tasks🟡 Untested
POST/tasksCreate new task🟡 Untested

Implementation Status: Complete but untested in production

Task Object

Properties

{
  id: string              // Task ID (format: task_xxx)
  title: string           // Task title
  description: string     // Detailed description
  status: string          // "pending" | "in_progress" | "completed" | "cancelled"
  priority: string        // "low" | "medium" | "high" | "urgent"
  assignedTo?: string     // Agent or user ID
  assigneeType: string    // "agent" | "user"
  spaceId?: string        // Associated workspace
  organizationId: string  // Owner organization
  createdBy: string       // Creator user ID
  createdAt: string       // ISO 8601 timestamp
  updatedAt: string       // ISO 8601 timestamp
  dueDate?: string        // ISO 8601 timestamp
  completedAt?: string    // ISO 8601 timestamp
  metadata: object        // Additional task context
}

Example Object

{
  "id": "task_abc123",
  "title": "Analyze Q4 sales data",
  "description": "Review Q4 sales performance and identify trends",
  "status": "in_progress",
  "priority": "high",
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent",
  "spaceId": "space_456",
  "organizationId": "org_123",
  "createdBy": "user_789",
  "createdAt": "2025-12-09T09:00:00Z",
  "updatedAt": "2025-12-09T10:30:00Z",
  "dueDate": "2025-12-10T17:00:00Z",
  "metadata": {
    "tags": ["sales", "analytics", "quarterly"],
    "source": "api"
  }
}

List Tasks

Retrieve tasks for your organization with optional filtering.

Request

GET /api/v1/tasks

Headers:

Authorization: Bearer td_xxxxx...

Query Parameters:

  • status (string, optional) - Filter by status: pending, in_progress, completed, cancelled
  • assignedTo (string, optional) - Filter by agent or user ID
  • spaceId (string, optional) - Filter by workspace
  • priority (string, optional) - Filter by priority: low, medium, high, urgent
  • limit (number, optional) - Maximum results (default: 50, max: 100)

Response

Success (200 OK):

[
  {
    "id": "task_abc123",
    "title": "Analyze Q4 sales data",
    "description": "Review Q4 sales performance and identify trends",
    "status": "in_progress",
    "priority": "high",
    "assignedTo": "agent_xyz789",
    "assigneeType": "agent",
    "spaceId": "space_456",
    "organizationId": "org_123",
    "createdBy": "user_789",
    "createdAt": "2025-12-09T09:00:00Z",
    "updatedAt": "2025-12-09T10:30:00Z",
    "dueDate": "2025-12-10T17:00:00Z",
    "metadata": {
      "tags": ["sales", "analytics", "quarterly"]
    }
  },
  {
    "id": "task_def456",
    "title": "Review customer feedback",
    "description": "Summarize customer feedback from December",
    "status": "pending",
    "priority": "medium",
    "assignedTo": "user_456",
    "assigneeType": "user",
    "organizationId": "org_123",
    "createdBy": "user_789",
    "createdAt": "2025-12-09T11:00:00Z",
    "updatedAt": "2025-12-09T11:00:00Z",
    "dueDate": "2025-12-15T17:00:00Z",
    "metadata": {
      "tags": ["feedback", "customer-success"]
    }
  }
]

Empty result:

[]

Error (401 Unauthorized):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Examples

List all tasks:

curl https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filter by status:

curl "https://cc.teamday.ai/api/v1/tasks?status=pending" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filter by agent:

curl "https://cc.teamday.ai/api/v1/tasks?assignedTo=agent_xyz789" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filter by space:

curl "https://cc.teamday.ai/api/v1/tasks?spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Combine filters:

curl "https://cc.teamday.ai/api/v1/tasks?status=in_progress&spaceId=space_456&priority=high" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Limit results:

curl "https://cc.teamday.ai/api/v1/tasks?limit=10" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Create Task

Create a new task for your organization.

Request

POST /api/v1/tasks

Headers:

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Body:

{
  "title": "Analyze Q4 sales data",
  "description": "Review Q4 sales performance and identify trends",
  "status": "pending",
  "priority": "high",
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent",
  "spaceId": "space_456",
  "dueDate": "2025-12-10T17:00:00Z",
  "metadata": {
    "tags": ["sales", "analytics", "quarterly"],
    "source": "api"
  }
}

Required Fields:

  • title (string) - Task title (max 200 characters)

Optional Fields:

  • description (string) - Detailed description
  • status (string) - Initial status (default: "pending")
    • Options: "pending", "in_progress", "completed", "cancelled"
  • priority (string) - Priority level (default: "medium")
    • Options: "low", "medium", "high", "urgent"
  • assignedTo (string) - Agent or user ID
  • assigneeType (string) - Type of assignee (default: "user")
    • Options: "agent", "user"
  • spaceId (string) - Workspace ID
  • dueDate (string) - ISO 8601 timestamp
  • metadata (object) - Additional context (tags, custom fields, etc.)

Response

Success (201 Created):

{
  "id": "task_abc123",
  "title": "Analyze Q4 sales data",
  "description": "Review Q4 sales performance and identify trends",
  "status": "pending",
  "priority": "high",
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent",
  "spaceId": "space_456",
  "organizationId": "org_123",
  "createdBy": "user_789",
  "createdAt": "2025-12-09T09:00:00Z",
  "updatedAt": "2025-12-09T09:00:00Z",
  "dueDate": "2025-12-10T17:00:00Z",
  "metadata": {
    "tags": ["sales", "analytics", "quarterly"],
    "source": "api"
  }
}

Error (400 Bad Request):

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: title"
}

Error (401 Unauthorized):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Examples

Minimal task:

curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review customer feedback"
  }'

Task with all fields:

curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyze Q4 sales data",
    "description": "Review Q4 sales performance and identify trends. Focus on regional differences and product category performance.",
    "status": "pending",
    "priority": "high",
    "assignedTo": "agent_xyz789",
    "assigneeType": "agent",
    "spaceId": "space_456",
    "dueDate": "2025-12-10T17:00:00Z",
    "metadata": {
      "tags": ["sales", "analytics", "quarterly"],
      "source": "api",
      "department": "sales"
    }
  }'

Task assigned to user:

curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Update Q4 presentation",
    "description": "Add latest sales figures to quarterly presentation",
    "assignedTo": "user_456",
    "assigneeType": "user",
    "priority": "medium",
    "dueDate": "2025-12-11T12:00:00Z"
  }'

Task Status Workflow

Tasks progress through the following states:

Pending

Status: "pending"

Description: Task created but not yet started. Default state for new tasks.

Next states: in_progress, cancelled

Use cases:

  • Backlog items
  • Queued work
  • Future tasks

In Progress

Status: "in_progress"

Description: Task actively being worked on.

Next states: completed, cancelled, pending (if paused)

Use cases:

  • Active work items
  • Agent execution
  • User tasks in progress

Completed

Status: "completed"

Description: Task finished successfully. Sets completedAt timestamp.

Terminal state: Yes (typically no further transitions)

Use cases:

  • Finished work
  • Successful agent execution
  • Archived tasks

Cancelled

Status: "cancelled"

Description: Task cancelled before completion.

Terminal state: Yes (typically no further transitions)

Use cases:

  • Deprioritized work
  • Duplicate tasks
  • Changed requirements

Priority Levels

Tasks support four priority levels:

Low

Priority: "low"

Use cases:

  • Nice-to-have improvements
  • Future enhancements
  • Non-urgent work

SLA: No specific deadline

Medium

Priority: "medium"

Use cases:

  • Regular work items
  • Standard tasks
  • Default priority

SLA: Within sprint/week

High

Priority: "high"

Use cases:

  • Important features
  • Customer requests
  • Time-sensitive work

SLA: Within 1-2 days

Urgent

Priority: "urgent"

Use cases:

  • Critical bugs
  • Production issues
  • Immediate action required

SLA: Same day

Assignee Types

Tasks can be assigned to agents or users:

Agent Assignment

Type: "agent"

Field: assignedTo = agent ID (format: agent_xxx)

Behavior:

  • Task can be automatically executed by agent
  • Track via Executions API
  • Agent can update task status

Example:

{
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent"
}

User Assignment

Type: "user"

Field: assignedTo = user ID (format: user_xxx)

Behavior:

  • Task appears in user's dashboard
  • User manually updates status
  • Email notifications (if enabled)

Example:

{
  "assignedTo": "user_456",
  "assigneeType": "user"
}

Unassigned

Field: assignedTo = null or omitted

Behavior:

  • Task visible to all organization members
  • Can be claimed by any user/agent
  • Appears in organization task pool

Metadata & Custom Fields

Use the metadata object to store additional task information:

Common Patterns

Tags:

{
  "metadata": {
    "tags": ["urgent", "customer-facing", "bug"]
  }
}

Custom fields:

{
  "metadata": {
    "department": "engineering",
    "project": "Q4-platform-upgrade",
    "estimatedHours": 8,
    "complexity": "medium"
  }
}

External references:

{
  "metadata": {
    "jiraTicket": "PROJ-123",
    "githubIssue": "https://github.com/org/repo/issues/456",
    "slackThread": "https://workspace.slack.com/archives/C123/p123456"
  }
}

Automation context:

{
  "metadata": {
    "source": "api",
    "createdBy": "automation-script",
    "triggeredBy": "webhook",
    "webhookId": "hook_123"
  }
}

Firestore Considerations

Important: Metadata values must be JSON-serializable:

  • ✅ Strings, numbers, booleans, arrays, objects
  • ❌ undefined (use null instead)
  • ❌ Functions
  • ❌ Dates (use ISO 8601 strings)

Filtering & Querying

By Status

Get all pending tasks:

curl "https://cc.teamday.ai/api/v1/tasks?status=pending" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Get completed tasks:

curl "https://cc.teamday.ai/api/v1/tasks?status=completed" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

By Assignee

Get all tasks for a specific agent:

curl "https://cc.teamday.ai/api/v1/tasks?assignedTo=agent_xyz789" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Get all tasks for a user:

curl "https://cc.teamday.ai/api/v1/tasks?assignedTo=user_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

By Space

Get all tasks in a workspace:

curl "https://cc.teamday.ai/api/v1/tasks?spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

By Priority

Get high-priority tasks:

curl "https://cc.teamday.ai/api/v1/tasks?priority=high" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Get urgent tasks:

curl "https://cc.teamday.ai/api/v1/tasks?priority=urgent" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Combined Filters

Get pending high-priority tasks for a specific agent:

curl "https://cc.teamday.ai/api/v1/tasks?status=pending&priority=high&assignedTo=agent_xyz789" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Common Patterns

Create Task for Agent

curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyze sales trends",
    "description": "Review last 30 days of sales data and identify trends",
    "assignedTo": "agent_research123",
    "assigneeType": "agent",
    "priority": "high",
    "metadata": {
      "tags": ["analytics", "sales"],
      "automatedTask": true
    }
  }'

Create User Task

curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review agent analysis",
    "description": "Review the sales analysis provided by Research Agent",
    "assignedTo": "user_manager456",
    "assigneeType": "user",
    "priority": "medium",
    "dueDate": "2025-12-11T17:00:00Z",
    "metadata": {
      "tags": ["review"],
      "relatedTask": "task_abc123"
    }
  }'

Track Agent Work

Create task when agent starts work:

# 1. Create task
TASK_ID=$(curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Process customer data",
    "assignedTo": "agent_data789",
    "assigneeType": "agent",
    "status": "in_progress"
  }' | jq -r '.id')

# 2. Execute agent (when working)
# curl -X POST https://cc.teamday.ai/api/v1/agents/agent_data789/execute ...

# 3. Update task to completed (manual for now)
# Future: Auto-update via webhooks or executions API

Workflow Automation

Create dependent tasks:

# 1. Research task
curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research market trends",
    "assignedTo": "agent_researcher",
    "assigneeType": "agent",
    "metadata": {
      "workflow": "market-analysis",
      "step": 1
    }
  }'

# 2. Analysis task (depends on step 1)
curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyze research findings",
    "assignedTo": "agent_analyst",
    "assigneeType": "agent",
    "status": "pending",
    "metadata": {
      "workflow": "market-analysis",
      "step": 2,
      "dependsOn": "task_step1_id"
    }
  }'

# 3. Report task (depends on step 2)
curl -X POST https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Generate market report",
    "assignedTo": "agent_writer",
    "assigneeType": "agent",
    "status": "pending",
    "metadata": {
      "workflow": "market-analysis",
      "step": 3,
      "dependsOn": "task_step2_id"
    }
  }'

Best Practices

Task Design

Titles:

  • Be specific and actionable
  • Start with verb (Analyze, Review, Create, Update)
  • Keep under 100 characters

Good examples:

  • "Analyze Q4 sales data for trends"
  • "Review and summarize customer feedback"
  • "Update quarterly presentation with latest metrics"

Avoid:

  • Vague titles: "Sales stuff", "Do the thing"
  • Very long titles that truncate

Descriptions:

  • Provide context and background
  • List specific requirements or acceptance criteria
  • Include links to relevant resources
  • Mention expected output

Status Management

Update status promptly:

  • Mark in_progress when starting work
  • Mark completed when done
  • Include completedAt timestamp for completed tasks

Use cancellation wisely:

  • Cancel duplicates immediately
  • Cancel deprioritized work
  • Add cancellation reason in metadata

Priority Guidelines

Be consistent:

  • Most tasks should be medium or low
  • Use high sparingly (< 20% of tasks)
  • Reserve urgent for true emergencies (< 5% of tasks)

Avoid priority inflation:

  • Don't mark everything as urgent
  • Review and downgrade priorities regularly
  • Focus on throughput, not just urgency

Assignment Strategy

Agent tasks:

  • Assign to agents for automatable work
  • Include clear instructions in description
  • Use metadata for agent-specific context

User tasks:

  • Assign to users for review/approval
  • Include all context needed for decision
  • Set realistic due dates

Unassigned tasks:

  • Use for task pools
  • Let team members self-assign
  • Good for flexible workloads

Metadata Usage

Standard fields:

{
  "metadata": {
    "tags": ["tag1", "tag2"],
    "department": "engineering",
    "priority": "high",
    "estimatedHours": 4
  }
}

Keep metadata clean:

  • Use consistent naming conventions
  • Document custom fields in your codebase
  • Avoid storing large objects (> 1KB)
  • Use references instead of duplicating data

Update Task (Future)

Coming soon: Update existing tasks via API

Expected endpoint:

PATCH /api/v1/tasks/[id]

Use cases:

  • Update status programmatically
  • Reassign tasks
  • Change priority
  • Update description

Current workaround: Use web interface to update tasks

Delete Task (Future)

Coming soon: Delete tasks via API

Expected endpoint:

DELETE /api/v1/tasks/[id]

Use cases:

  • Remove duplicate tasks
  • Clean up old tasks
  • Cancel and delete in one action

Current workaround: Set status to cancelled

Webhooks (Future)

Coming soon: Webhooks for task events

Planned events:

  • task.created
  • task.updated
  • task.status_changed
  • task.completed
  • task.assigned

Use cases:

  • Trigger automation on task creation
  • Notify external systems
  • Update dependent tasks
  • Send notifications

Error Handling

Common Errors

400 Bad Request:

  • Missing required field (title)
  • Invalid status value
  • Invalid priority value
  • Invalid assignee type

401 Unauthorized:

  • Missing Authorization header
  • Invalid or expired token

404 Not Found:

  • Task ID doesn't exist
  • Task belongs to different organization

500 Internal Server Error:

  • Database connectivity issues
  • Service temporarily unavailable

Validation Errors

Missing title:

{
  "error": true,
  "statusCode": 400,
  "message": "Missing required field: title"
}

Invalid status:

{
  "error": true,
  "statusCode": 400,
  "message": "Invalid status. Must be: pending, in_progress, completed, cancelled"
}

Invalid priority:

{
  "error": true,
  "statusCode": 400,
  "message": "Invalid priority. Must be: low, medium, high, urgent"
}

Need Help?

Issues with tasks?

  • Check error reference for troubleshooting
  • Verify required fields are provided
  • Validate status and priority values

Questions?

Last Updated: December 9, 2025