ClickUp Core Workflow A — Task Management

Overview

CRUD operations on ClickUp tasks via API v2. Tasks live in Lists and support assignees, priorities (1-4), statuses, due dates, tags, checklists, and custom fields.

Endpoints

Operation	Method	Endpoint
Create task	POST	/api/v2/list/{list_id}/task
Get task	GET	/api/v2/task/{task_id}
Update task	PUT	/api/v2/task/{task_id}
Delete task	DELETE	/api/v2/task/{task_id}
Get tasks in list	GET	/api/v2/list/{list_id}/task
Add task to list	POST	/api/v2/list/{list_id}/task/{task_id}
Create subtask	POST	/api/v2/list/{list_id}/task (with parent field)

Create Task

interface CreateTaskBody {
  name: string;                    // Required
  description?: string;            // Plain text
  markdown_description?: string;   // Markdown (use instead of description)
  assignees?: number[];            // Array of user IDs
  tags?: string[];                 // Tag names
  status?: string;                 // Status name (e.g., "to do", "in progress")
  priority?: 1 | 2 | 3 | 4 | null; // 1=Urgent, 2=High, 3=Normal, 4=Low
  due_date?: number;               // Unix timestamp in milliseconds
  due_date_time?: boolean;         // true = show time, false = date only
  start_date?: number;             // Unix ms
  start_date_time?: boolean;
  time_estimate?: number;          // Time estimate in milliseconds
  notify_all?: boolean;            // Notify assignees
  parent?: string;                 // Parent task ID (creates subtask)
  links_to?: string;               // Task ID to link to
  custom_fields?: Array<{
    id: string;                    // Custom field UUID
    value: any;                    // Type-dependent value
  }>;
}

async function createTask(listId: string, task: CreateTaskBody) {
  return clickupRequest(`/list/${listId}/task`, {
    method: 'POST',
    body: JSON.stringify(task),
  });
}

// Example: Create an urgent task with assignee
await createTask('900100200300', {
  name: 'Fix production bug in auth module',
  markdown_description: '## Bug\nLogin fails for SSO users\n\n## Steps\n1. Go to /login\n2. Click SSO',
  assignees: [183],
  priority: 1,
  status: 'in progress',
  due_date: Date.now() + 3600000,
  due_date_time: true,
  tags: ['bug', 'production'],
});

Get Tasks (with Filtering)

async function getTasks(listId: string, params: Record<string, string> = {}) {
  const query = new URLSearchParams({
    archived: 'false',
    include_closed: 'false',
    subtasks: 'true',
    ...params,
  });
  return clickupRequest(`/list/${listId}/task?${query}`);
}

// Filter by assignee and status
const tasks = await getTasks('900100200300', {
  'assignees[]': '183',
  'statuses[]': 'in progress',
  order_by: 'due_date',
  reverse: 'true',
  page: '0',          // Pagination: 100 tasks per page
});
// Response: { tasks: [...] }

Update Task

// Only include fields you want to change
async function updateTask(taskId: string, updates: Partial<CreateTaskBody>) {
  return clickupRequest(`/task/${taskId}`, {
    method: 'PUT',
    body: JSON.stringify(updates),
  });
}

// Change status and add assignee
await updateTask('abc123', {
  status: 'complete',
  assignees: { add: [456], rem: [] },  // Add/remove pattern for assignees on update
});

Create Subtask

await createTask('900100200300', {
  name: 'Write unit tests for auth fix',
  parent: 'abc123',  // Parent task ID makes this a subtask
  assignees: [183],
  priority: 3,
});

Bulk Operations

// Get all tasks across workspace with team-level endpoint
async function searchTasks(teamId: string, query: string) {
  return clickupRequest(`/team/${teamId}/task?${new URLSearchParams({
    page: '0',
    order_by: 'updated',
    reverse: 'true',
    include_closed: 'true',
    subtasks: 'true',
  })}`);
}

Error Handling

Status	Cause	Solution
400	Missing name field	Task name is required
401	Invalid token	Re-authenticate
404	Invalid list_id or task_id	Verify IDs via GET endpoints
403	No permission on this list	Check workspace membership

Resources

• Create Task API
• Update Task API
• Get Tasks API

Next Steps

For spaces, folders, and lists management see clickup-core-workflow-b.