> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daycopilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Tasks

> Advanced techniques for task management with the Day Copilot API

## Overview

This guide covers advanced task management patterns including batch operations, assignment workflows, draft management, and filtering strategies.

## Task Lifecycle

Understanding the complete task lifecycle helps you build robust integrations:

```mermaid theme={null}
graph TD
    CREATE[Create Task] --> PENDING[Status: Pending]
    PENDING --> ASSIGN[Assign to User]
    ASSIGN --> IN_PROGRESS[Status: In Progress]
    IN_PROGRESS --> DRAFT[Create Draft]
    DRAFT --> REVIEW[Review Changes]
    REVIEW --> PUBLISH[Publish Draft]
    PUBLISH --> COMPLETE[Mark Complete]
    COMPLETE --> ARCHIVE[Archive/Delete]

    DRAFT --> DISCARD[Discard Draft]
    DISCARD --> IN_PROGRESS
    PENDING --> CANCEL[Cancel Task]
    IN_PROGRESS --> CANCEL
```

## Creating Tasks

### Basic Task Creation

```javascript theme={null}
const task = await fetch('https://app.daycopilot.ai/api/v1/tasks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Complete Q4 planning',
    description: 'Finalize objectives and key results',
    priority: 'high',
    status: 'pending',
    due_date: '2025-12-15T17:00:00Z'
  })
}).then(r => r.json());

console.log('Task ID:', task.data.id);
```

### Task in Context

Create task within a specific context (project):

```javascript theme={null}
const task = await createTask({
  title: 'Review API documentation',
  context_id: 'project-uuid',
  priority: 'medium'
});
```

### Task with Time Estimate

```javascript theme={null}
const task = await createTask({
  title: 'Implement user authentication',
  time_estimate_minutes: 240, // 4 hours
  due_date: '2025-11-10T17:00:00Z'
});
```

## Assigning Tasks

### Assign to User

```bash theme={null}
POST /api/v1/tasks/{taskId}/assign
{
  "user_email": "colleague@example.com",
  "notify": true
}
```

**Response:**

```json theme={null}
{
  "data": {
    "task_id": "task-uuid",
    "assignee": {
      "user_id": "user-uuid",
      "email": "colleague@example.com",
      "assigned_at": "2025-11-02T12:00:00Z"
    }
  }
}
```

### Multiple Assignees

```javascript theme={null}
// Assign to multiple users
const assignees = ['alice@example.com', 'bob@example.com'];

for (const email of assignees) {
  await fetch(`https://app.daycopilot.ai/api/v1/tasks/${taskId}/assign`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ user_email: email, notify: true })
  });
}
```

### Get Assigned Tasks

```bash theme={null}
# Get tasks assigned to me
GET /api/v1/tasks/assigned

# Filter by status
GET /api/v1/tasks/assigned?status=in_progress
```

## Filtering & Searching

### By Status

```bash theme={null}
GET /api/v1/tasks?status=pending,in_progress
```

### By Priority

```bash theme={null}
GET /api/v1/tasks?priority=high,urgent
```

### By Context

```bash theme={null}
GET /api/v1/tasks?context_id=project-uuid
```

### By Due Date Range

```bash theme={null}
GET /api/v1/tasks?due_after=2025-11-01&due_before=2025-11-30
```

### Full-Text Search

```bash theme={null}
GET /api/v1/tasks/search?q=api+documentation
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "task-uuid",
      "title": "Complete API documentation",
      "description": "Write comprehensive API docs",
      "relevance_score": 0.95
    }
  ]
}
```

### Complex Filtering Example

```javascript theme={null}
const filters = {
  status: ['pending', 'in_progress'],
  priority: ['high', 'urgent'],
  context_id: 'project-uuid',
  assigned_to_me: true,
  due_before: '2025-12-01T00:00:00Z',
  limit: 50,
  offset: 0
};

const queryString = new URLSearchParams(filters).toString();
const tasks = await fetch(
  `https://app.daycopilot.ai/api/v1/tasks?${queryString}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
).then(r => r.json());
```

## Draft Workflow

### Making Changes as Draft

```javascript theme={null}
// Update task (creates draft)
const draft = await fetch(`https://app.daycopilot.ai/api/v1/tasks/${taskId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Updated title',
    description: 'Updated description',
    priority: 'urgent'
  })
}).then(r => r.json());

console.log('Draft version:', draft.data.version_minor);
console.log('Published:', draft.data.is_published); // false
```

### Publishing Draft

```javascript theme={null}
const published = await fetch(
  `https://app.daycopilot.ai/api/v1/tasks/${taskId}/draft`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ action: 'accept' })
  }
).then(r => r.json());

console.log('New version:', published.data.version_major); // Incremented
```

### Discarding Draft

```javascript theme={null}
await fetch(`https://app.daycopilot.ai/api/v1/tasks/${taskId}/draft`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ action: 'discard' })
});

// Task reverted to last published state
```

## Comments & Discussion

### Add Comment

```javascript theme={null}
const comment = await fetch(
  `https://app.daycopilot.ai/api/v1/tasks/${taskId}/comments`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: 'Updated priority based on stakeholder feedback'
    })
  }
).then(r => r.json());

console.log('Comment timestamp:', comment.data.created_at);
```

### List Comments

```bash theme={null}
GET /api/v1/tasks/{taskId}/comments
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "task_id": "task-uuid",
      "message": "Great progress!",
      "created_at": "2025-11-02T12:00:00Z",
      "user_id": "user-uuid",
      "user_name": "Alice Smith"
    }
  ]
}
```

### Update Comment

```javascript theme={null}
// Use timestamp as ID
const timestamp = '2025-11-02T12:00:00Z';

await fetch(
  `https://app.daycopilot.ai/api/v1/tasks/${taskId}/comments/${timestamp}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: 'Updated comment text'
    })
  }
);
```

## Status Management

### Update Status

```javascript theme={null}
// Direct status update (no draft)
await fetch(`https://app.daycopilot.ai/api/v1/tasks/${taskId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'in_progress',
    publish: true  // Skip draft workflow
  })
});
```

### Complete Task

```bash theme={null}
POST /api/v1/tasks/{taskId}/complete
```

This is a shortcut for:

```javascript theme={null}
{
  "status": "completed",
  "completed_at": "2025-11-02T12:00:00Z",
  "publish": true
}
```

### Cancel Task

```javascript theme={null}
await fetch(`https://app.daycopilot.ai/api/v1/tasks/${taskId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'canceled',
    cancellation_reason: 'Requirements changed',
    publish: true
  })
});
```

## Batch Operations

### Create Multiple Tasks

```javascript theme={null}
const tasks = [
  { title: 'Task 1', priority: 'high' },
  { title: 'Task 2', priority: 'medium' },
  { title: 'Task 3', priority: 'low' }
];

const created = await Promise.all(
  tasks.map(task =>
    fetch('https://app.daycopilot.ai/api/v1/tasks', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(task)
    }).then(r => r.json())
  )
);

console.log(`Created ${created.length} tasks`);
```

### Bulk Status Update

```javascript theme={null}
// Get all pending tasks
const pending = await fetch(
  'https://app.daycopilot.ai/api/v1/tasks?status=pending',
  { headers: { 'Authorization': `Bearer ${token}` } }
).then(r => r.json());

// Update all to in_progress
await Promise.all(
  pending.data.map(task =>
    fetch(`https://app.daycopilot.ai/api/v1/tasks/${task.id}`, {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ status: 'in_progress', publish: true })
    })
  )
);
```

## Pagination

### Iterate Through All Tasks

```javascript theme={null}
async function getAllTasks(token) {
  const allTasks = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://app.daycopilot.ai/api/v1/tasks?limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    ).then(r => r.json());

    allTasks.push(...response.data);
    hasMore = response.meta.pagination.hasMore;
    offset += limit;
  }

  return allTasks;
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Contexts for Organization">
    Group related tasks into contexts. This makes filtering, sharing, and bulk operations much easier.

    ```javascript theme={null}
    // Good: Tasks in context
    await createTask({
      title: 'Review PR #123',
      context_id: 'engineering-project-uuid'
    });
    ```
  </Accordion>

  <Accordion title="Set Due Dates">
    Always set due dates for time-sensitive tasks. This enables timeline views and reminders.

    ```javascript theme={null}
    await createTask({
      title: 'Submit quarterly report',
      due_date: '2025-12-31T23:59:59Z',
      priority: 'high'
    });
    ```
  </Accordion>

  <Accordion title="Use Priority Consistently">
    Establish team conventions for priority levels:

    * **Urgent**: Do immediately, blocks others
    * **High**: Important, do this week
    * **Medium**: Normal priority
    * **Low**: Nice to have, when time permits
  </Accordion>

  <Accordion title="Add Comments for Context">
    Use comments instead of editing descriptions to preserve history:

    ```javascript theme={null}
    // Instead of updating description
    await addComment(taskId, 'Blocker: Waiting for API key from DevOps');
    ```
  </Accordion>

  <Accordion title="Handle Drafts Appropriately">
    * Use drafts for major changes that need review
    * Skip drafts for status updates and quick fixes
    * Publish drafts promptly to avoid conflicts
  </Accordion>
</AccordionGroup>

## Common Patterns

### Daily Standup Report

```javascript theme={null}
async function getStandupReport(token) {
  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);

  // Completed yesterday
  const completed = await fetch(
    `https://app.daycopilot.ai/api/v1/tasks?` +
    `status=completed&` +
    `completed_after=${yesterday.toISOString()}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(r => r.json());

  // In progress today
  const inProgress = await fetch(
    'https://app.daycopilot.ai/api/v1/tasks?status=in_progress',
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(r => r.json());

  return {
    completed: completed.data,
    inProgress: inProgress.data
  };
}
```

### Overdue Tasks Alert

```javascript theme={null}
async function getOverdueTasks(token) {
  const now = new Date().toISOString();

  const overdue = await fetch(
    `https://app.daycopilot.ai/api/v1/tasks?` +
    `status=pending,in_progress&` +
    `due_before=${now}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(r => r.json());

  return overdue.data;
}
```

### Task Template

```javascript theme={null}
const taskTemplates = {
  bugFix: {
    priority: 'high',
    status: 'pending',
    context_id: 'engineering-uuid',
    labels: ['bug', 'needs-triage']
  },
  feature: {
    priority: 'medium',
    status: 'pending',
    context_id: 'product-uuid',
    labels: ['feature', 'roadmap']
  }
};

// Use template
const bugTask = await createTask({
  ...taskTemplates.bugFix,
  title: 'Fix login redirect issue',
  description: 'Users report redirect loop after login'
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Working with Events" icon="calendar" href="/guides/working-with-events">
    Manage calendar events and attendees
  </Card>

  <Card title="Draft Workflow" icon="code-branch" href="/concepts/draft-workflow">
    Deep dive into versioning
  </Card>

  <Card title="Tasks API Reference" icon="code" href="/api-reference/tasks/list">
    Complete API documentation
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle errors in production
  </Card>
</CardGroup>