# Tasks API

Create and manage tasks, track work items, and coordinate agent assignments with the TeamDay Tasks API.

# 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](https://docs.teamday.ai/api/authentication) required

---

## Endpoints Overview

| Method | Endpoint | Description | Status |
|--------|----------|-------------|--------|
| GET | `/tasks` | List tasks | 🟡 Untested |
| POST | `/tasks` | Create new task | 🟡 Untested |

**Implementation Status:** Complete but untested in production

---

## Task Object

### Properties

```typescript
{
  id: string              // Task ID (format: task-{timestamp}-{random})
  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
  spaceId?: string        // Associated workspace
  organizationId: string  // Owner organization
  createdBy: string       // Creator (agent ID or user ID)
  createdAt: string       // ISO 8601 timestamp
  completedAt?: string    // ISO 8601 timestamp
}
```

### Example Object

```json
{
  "id": "task-1734567890-abc",
  "title": "Analyze Q4 sales data",
  "description": "Review Q4 sales performance and identify trends",
  "status": "in_progress",
  "priority": "high",
  "assignedTo": "abc123def456",
  "spaceId": "space_456",
  "organizationId": "org_123",
  "createdBy": "user_789",
  "createdAt": "2025-12-09T09:00:00Z"
}
```

---

## List Tasks

Retrieve tasks for your organization with optional filtering.

### Request

```http
GET /api/v1/tasks
```

**Headers:**
```http
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

### Response

**Success (200 OK):**
```json
{
  "success": true,
  "tasks": [
    {
      "id": "task-1734567890-abc",
      "title": "Analyze Q4 sales data",
      "description": "Review Q4 sales performance and identify trends",
      "status": "in_progress",
      "priority": "high",
      "assignedTo": "abc123def456",
      "spaceId": "space_456",
      "organizationId": "org_123",
      "createdBy": "user_789",
      "createdAt": "2025-12-09T09:00:00Z"
    },
    {
      "id": "task-1734574800-def",
      "title": "Review customer feedback",
      "description": "Summarize customer feedback from December",
      "status": "pending",
      "priority": "medium",
      "assignedTo": "user_456",
      "organizationId": "org_123",
      "createdBy": "user_789",
      "createdAt": "2025-12-09T11:00:00Z"
    }
  ]
}
```

**Empty result:**
```json
{
  "success": true,
  "tasks": []
}
```

**Error (401 Unauthorized):**
```json
{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Unauthorized. Invalid or expired token"
}
```

### Examples

**List all tasks:**
```bash
curl https://cc.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

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

**Filter by agent:**
```bash
curl "https://cc.teamday.ai/api/v1/tasks?assignedTo=abc123def456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

**Filter by space:**
```bash
curl "https://cc.teamday.ai/api/v1/tasks?spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

**Combine filters:**
```bash
curl "https://cc.teamday.ai/api/v1/tasks?status=in_progress&spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

---

## Create Task

Create a new task for your organization.

### Request

```http
POST /api/v1/tasks
```

**Headers:**
```http
Authorization: Bearer td_xxxxx...
Content-Type: application/json
```

**Body:**
```json
{
  "title": "Analyze Q4 sales data",
  "description": "Review Q4 sales performance and identify trends",
  "assignTo": "abc123def456",
  "priority": "high",
  "spaceId": "space_456"
}
```

**Required Fields:**
- `title` (string) - Task title

**Optional Fields:**
- `description` (string) - Detailed description
- `priority` (string) - Priority level (default: `"medium"`)
  - Options: `"low"`, `"medium"`, `"high"`, `"urgent"`
- `assignTo` (string) - Agent or user ID to assign to
- `spaceId` (string) - Workspace ID

### Response

**Success (200 OK):**
```json
{
  "success": true,
  "task": {
    "id": "task-1734567890-abc",
    "title": "Analyze Q4 sales data",
    "description": "Review Q4 sales performance and identify trends",
    "status": "pending",
    "priority": "high",
    "assignedTo": "abc123def456",
    "spaceId": "space_456",
    "organizationId": "org_123",
    "createdBy": "user_789",
    "createdAt": "2025-12-09T09:00:00Z"
  }
}
```

**Error (400 Bad Request):**
```json
{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: title"
}
```

**Error (401 Unauthorized):**
```json
{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Unauthorized. Invalid or expired token"
}
```

### Examples

**Minimal task:**
```bash
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:**
```bash
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.",
    "priority": "high",
    "assignTo": "abc123def456",
    "spaceId": "space_456"
  }'
```

**Task assigned to user:**
```bash
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",
    "assignTo": "user_456",
    "priority": "medium"
  }'
```

---

## 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

---

## Assignment

Tasks can be assigned to agents or users via the `assignedTo` field:

### Agent Assignment

**Field:** `assignedTo` = agent ID (Firestore auto-generated)

**Behavior:**
- Task can be automatically executed by agent
- Track via [Executions API](https://docs.teamday.ai/api/executions)
- Agent can update task status

### User Assignment

**Field:** `assignedTo` = user ID

**Behavior:**
- Task appears in user's dashboard
- User manually updates status

### 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

---

## Filtering & Querying

### By Status

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

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

### By Assignee

Get all tasks for a specific agent:
```bash
curl "https://cc.teamday.ai/api/v1/tasks?assignedTo=abc123def456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

Get all tasks for a user:
```bash
curl "https://cc.teamday.ai/api/v1/tasks?assignedTo=user_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

### By Space

Get all tasks in a workspace:
```bash
curl "https://cc.teamday.ai/api/v1/tasks?spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

### Combined Filters

Get pending tasks for a specific agent:
```bash
curl "https://cc.teamday.ai/api/v1/tasks?status=pending&assignedTo=abc123def456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"
```

---

## Common Patterns

### Create Task for Agent

```bash
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",
    "assignTo": "abc123def456",
    "priority": "high"
  }'
```

### Create User Task

```bash
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",
    "assignTo": "user_manager456",
    "priority": "medium"
  }'
```

### Track Agent Work

Create task when agent starts work:
```bash
# 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",
    "assignTo": "abc123def456"
  }' | jq -r '.task.id')

# 2. Execute agent
# curl -X POST https://cc.teamday.ai/api/v1/agents/abc123def456/execute ...

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

### Workflow Automation

Create dependent tasks:
```bash
# 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",
    "assignTo": "abc123def456",
    "priority": "high"
  }'

# 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",
    "assignTo": "ghi789jkl012",
    "priority": "high"
  }'

# 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",
    "assignTo": "mno345pqr678",
    "priority": "medium"
  }'
```

---

## 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

### General Tips

- Keep task titles specific and actionable
- Use `description` for detailed context
- Assign tasks to the right agent or user for the job

---

## Update Task (Future)

**Coming soon:** Update existing tasks via API

**Expected endpoint:**
```http
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:**
```http
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

**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:**
```json
{
  "error": true,
  "statusCode": 400,
  "message": "Missing required field: title"
}
```

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

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

---

## Related Resources

- [Agents API](https://docs.teamday.ai/api/agents) - Create and manage agents
- [Executions API](https://docs.teamday.ai/api/executions) - Track agent execution history
- [Authentication](https://docs.teamday.ai/api/authentication) - PAT token setup
- [Error Reference](https://docs.teamday.ai/api/errors) - Complete error documentation

---

## Need Help?

**Issues with tasks?**
- Check [error reference](https://docs.teamday.ai/api/errors) for troubleshooting
- Verify required fields are provided
- Validate status and priority values

**Questions?**
- 📧 Email: support at teamday.ai
- 💬 Discord: [Join community](https://discord.gg/teamday)
- 🐛 Report bugs: [GitHub Issues](https://github.com/TeamDay-AI/teamday/issues)

---

**Last Updated:** February 19, 2026