--- updatedAt: 2026-01-28T15:07:36.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # Managing Tasks Create, retrieve, update, and delete tasks within a task board. ## Endpoints | Method | Endpoint | Description | | :----- | :------------------------------------------------ | :---------- | | GET | /tasks/v1/taskboards/{taskBoardId}/tasks | Get tasks | | POST | /tasks/v1/taskboards/{taskBoardId}/tasks | Create task | | PUT | /tasks/v1/taskboards/{taskBoardId}/tasks/{taskId} | Update task | | DELETE | /tasks/v1/taskboards/{taskBoardId}/tasks/{taskId} | Delete task | *** ## Get Tasks Retrieve tasks with optional filters. ### Query Parameters | Parameter | Type | Required | Default | Description | | :-------- | :------ | :------- | :------ | :--------------------------------------------------------- | | taskIds | array | No | - | Filter by specific task IDs | | labelIds | array | No | - | Filter by label IDs | | userIds | array | No | - | Filter by assigned user IDs | | status | string | No | `all` | Filter by status: `draft`, `published`, `completed`, `all` | | limit | integer | No | 10 | Results per page (1-100) | | offset | integer | No | 0 | Pagination offset | ### Example Request ```bash curl --request GET \ --url 'https://api.connecteam.com/tasks/v1/taskboards/12345/tasks?status=published&limit=50' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Response ```json { "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "tasks": [ { "id": "task-abc123", "title": "Complete safety inspection", "userIds": [9170357, 9170358], "status": "published", "type": "oneTime", "startTime": 1704110400, "dueDate": 1704196800, "labelIds": ["label-123", "label-456"], "isArchived": false, "subTasks": [ { "id": "subtask-001", "title": "Check fire extinguishers", "isCompleted": true }, { "id": "subtask-002", "title": "Inspect emergency exits", "isCompleted": false } ], "description": [ { "type": "html", "html": "

Monthly safety inspection checklist

" } ] } ] }, "paging": { "offset": 1 } } ``` ### Task Response Fields | Field | Type | Description | | :---------- | :------ | :----------------------------------- | | id | string | Unique task identifier | | title | string | Task title | | userIds | array | Assigned user IDs | | status | string | `draft`, `published`, or `completed` | | type | string | `oneTime` or `recurring` | | startTime | integer | Start timestamp (Unix seconds) | | dueDate | integer | Due date timestamp (Unix seconds) | | labelIds | array | Associated label IDs | | isArchived | boolean | Whether task is archived | | subTasks | array | List of sub-tasks | | description | array | Task description content | *** ## Create Task Create a new task and assign it to users. ### Request Body | Field | Type | Required | Description | | :---------- | :------ | :------- | :-------------------------------------------- | | title | string | Yes | Task title | | userIds | array | Yes | User IDs to assign (empty = draft only) | | status | string | Yes | `draft`, `published`, or `completed` | | startTime | integer | No | Start timestamp (Unix seconds) | | dueDate | integer | No | Due date timestamp (Unix seconds) | | labelIds | array | No | Label IDs to apply | | type | string | No | `oneTime` (default) or `recurring` | | isArchived | boolean | No | Archive status (default: false) | | subTasks | array | No | Initial sub-tasks | | description | object | No | Task description with content and attachments | ### Description Object | Field | Type | Required | Description | | :---------- | :----- | :------- | :--------------------------------------------- | | content | string | Yes | UTF-8 text content | | attachments | array | No | File attachments (fileId from Attachments API) | > ⚠️ Group Tasks > > If you specify **multiple userIds**, it creates a **group task** - all users see the same task and can collaborate. For **individual tasks** (each user gets their own copy), make separate API calls. ### Example: Create Published Task ```bash curl --request POST \ --url https://api.connecteam.com/tasks/v1/taskboards/12345/tasks \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "title": "Complete onboarding checklist", "userIds": [9170357], "status": "published", "dueDate": 1704196800, "labelIds": ["label-onboarding"], "subTasks": [ { "title": "Read employee handbook" }, { "title": "Complete HR forms" }, { "title": "Setup workstation" } ], "description": { "content": "Welcome! Please complete all items before your first week ends." } }' ``` ### Example: Create Draft Task ```bash curl --request POST \ --url https://api.connecteam.com/tasks/v1/taskboards/12345/tasks \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "title": "Quarterly review template", "userIds": [], "status": "draft", "description": { "content": "Template for Q1 reviews - assign to managers when ready" } }' ``` ### Example: Create Task with Attachment ```bash curl --request POST \ --url https://api.connecteam.com/tasks/v1/taskboards/12345/tasks \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "title": "Review training materials", "userIds": [9170357], "status": "published", "description": { "content": "Please review the attached training document", "attachments": [ { "fileId": "file-training-doc-123" } ] } }' ``` *** ## Update Task Modify an existing task. ### Request Body Same fields as create, but `id` comes from the path parameter. > 📝 Attachment Replacement > > When updating a task with attachments, the new attachments **replace** all existing ones. Include all attachments you want to retain. ### Example: Complete a Task ```bash curl --request PUT \ --url https://api.connecteam.com/tasks/v1/taskboards/12345/tasks/task-abc123 \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "title": "Complete safety inspection", "userIds": [9170357], "status": "completed" }' ``` ### Example: Reassign Task ```bash curl --request PUT \ --url https://api.connecteam.com/tasks/v1/taskboards/12345/tasks/task-abc123 \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "title": "Complete safety inspection", "userIds": [9170358, 9170359], "status": "published" }' ``` *** ## Delete Task Remove a task from the task board. ### Example ```bash curl --request DELETE \ --url https://api.connecteam.com/tasks/v1/taskboards/12345/tasks/task-abc123 \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Response ```json { "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": {} } ``` *** ## Integration Example ```javascript class TaskManager { constructor(apiKey, taskBoardId) { this.apiKey = apiKey; this.taskBoardId = taskBoardId; this.baseUrl = `https://api.connecteam.com/tasks/v1/taskboards/${taskBoardId}/tasks`; } async createTask(title, userIds, options = {}) { const response = await fetch(this.baseUrl, { method: 'POST', headers: { 'X-API-KEY': this.apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ title, userIds, status: options.status || 'published', dueDate: options.dueDate, labelIds: options.labelIds || [], subTasks: options.subTasks || [], description: options.description }) }); return response.json(); } async completeTask(taskId) { const task = await this.getTask(taskId); return this.updateTask(taskId, { ...task, status: 'completed' }); } async assignToNewUsers(taskId, newUserIds) { const task = await this.getTask(taskId); return this.updateTask(taskId, { ...task, userIds: newUserIds }); } } // Usage const tasks = new TaskManager('YOUR_API_KEY', 12345); await tasks.createTask('Weekly report', [9170357], { dueDate: Math.floor(Date.now() / 1000) + 86400 * 7, subTasks: [ { title: 'Gather metrics' }, { title: 'Write summary' }, { title: 'Submit for review' } ] }); ``` *** ## Error Responses ### 404 Not Found ```json { "detail": "Task not found" } ``` ### 400 Bad Request **File not found:** ```json { "detail": "File not found, file_id: file-invalid" } ``` **File not uploaded:** ```json { "detail": "File upload process not completed for file_id: file-123" } ``` *** [API Reference](https://developer.connecteam.com/reference/)