> For the complete documentation index, see [llms.txt](https://docs.kick.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kick.co/api/api-reference/tasks.md).

# Tasks

List and read the tasks and task groups of a client workspace, read a task's message thread, and post messages to it.

Tasks are the work items of a workspace: requests to the business owner, close checklist steps, reviews, and the tasks Kick creates on its own, such as a broken bank connection. All five endpoints are nested under the workspace.

The API reads tasks and task groups but doesn't create, edit, or delete them. To react to those changes, subscribe to the task webhooks listed at the end of this page.

### The task resource

* `status` is one of `todo`, `in_progress`, `done`, or `cancelled`.
* `priority` is `urgent`, `high`, `medium`, `low`, or `null` when none is set.
* `type` says what kind of task it is, such as `question`, `file`, `transactions`, `reconciliation`, or `connection_broken`. The spec lists every value. Treat a value you don't recognize as a generic task, because new types are added over time.
* `entityIds` are the workspace's entities the task is assigned to, as on [Entities](https://docs.kick.co/api/api-reference/entities.md). A task can cover several entities or none.
* `groupId` points to one of the workspace's [task groups](#task-groups), or is `null` when the task is ungrouped.
* `assigneeId`, `createdById`, and `completedById` are user uuids, as on [Users](https://docs.kick.co/api/api-reference/users.md). `createdById` is `null` for tasks Kick created. `completedById` and `completedAt` record who marked the task as done and when. Both are `null` while the task isn't done, and they are cleared when it is reopened. `completedById` is also `null` when Kick completed the task.
* `dueDate` is a calendar day as `YYYY-MM-DD`, or `null`.
* `metadata.transactionIds` lists the [Transactions](https://docs.kick.co/api/api-reference/transactions.md) a `transactions` or `transaction_review` task covers. Deleted transactions are left out. The list is empty when the task selects its transactions by other criteria, and `null` on every other task type. More `metadata` fields may be added.

Pass `relations` to expand the referenced records inline: `entities` fills `entities`, and `assignee`, `createdBy`, and `completedBy` fill the matching user objects. Without it, those fields are absent and only the ids come back.

### List tasks

Tasks come back newest first and are paged with `limit` and `offset`. See [Paging](https://docs.kick.co/api/readme.md#paging).

* Multi-value filters (`ids`, `statuses`, `priorities`, `types`, `groupIds`, `entityIds`, `assigneeIds`, `createdByIds`, `completedByIds`) take a single value or a repeated query param, and match any of the values given.
* An `entityIds` value that isn't an entity of the workspace is rejected with `400`.
* `isUnassigned=true` keeps only unassigned tasks. Combined with `assigneeIds`, it adds unassigned tasks to the tasks of those users. `isUnassigned=false` keeps only assigned tasks.
* `dueDateStart`/`dueDateEnd`, `createdAtStart`/`createdAtEnd`, and `completedAtStart`/`completedAtEnd` are inclusive calendar days as `YYYY-MM-DD`. Creation and completion days are read in the workspace's timezone. A start after its end is rejected with `400`.
* `search` matches text in the title, case-insensitive.

## List tasks

> Returns the workspace's tasks, newest first. Optional filters narrow the list by task (\`ids\`), \`statuses\`, \`priorities\`, task type (\`types\`), task group (\`groupIds\`), entity (\`entityIds\`), assignee (\`assigneeIds\`, \`isUnassigned\`), creator (\`createdByIds\`), completer (\`completedByIds\`), due date (\`dueDateStart\`/\`dueDateEnd\`), creation and completion day (\`createdAtStart\`/\`createdAtEnd\`, \`completedAtStart\`/\`completedAtEnd\`) and title (\`search\`). Date ranges are inclusive calendar days. Results are paged with \`limit\`/\`offset\`. Pass \`relations=entities\` to include the assigned entities in \`entities\`, and \`relations=assignee\`, \`relations=createdBy\` or \`relations=completedBy\` to include the referenced users.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/workspaces/{workspaceId}/tasks":{"get":{"description":"Returns the workspace's tasks, newest first. Optional filters narrow the list by task (`ids`), `statuses`, `priorities`, task type (`types`), task group (`groupIds`), entity (`entityIds`), assignee (`assigneeIds`, `isUnassigned`), creator (`createdByIds`), completer (`completedByIds`), due date (`dueDateStart`/`dueDateEnd`), creation and completion day (`createdAtStart`/`createdAtEnd`, `completedAtStart`/`completedAtEnd`) and title (`search`). Date ranges are inclusive calendar days. Results are paged with `limit`/`offset`. Pass `relations=entities` to include the assigned entities in `entities`, and `relations=assignee`, `relations=createdBy` or `relations=completedBy` to include the referenced users.","operationId":"tasks.list","parameters":[{"in":"path","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","schema":{"default":100,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"nullable":true,"type":"integer"}},{"description":"Related data to include in the response: `entities`, `assignee`, `createdBy`, `completedBy`. A single value or a repeated `relations` query param both work. Relations that are not requested are left out of the response.","in":"query","name":"relations","schema":{"items":{"enum":["entities","assignee","createdBy","completedBy"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only these tasks. A single value or a repeated `ids` query param both work.","in":"query","name":"ids","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks in any of these statuses. A single value or a repeated `statuses` query param both work.","in":"query","name":"statuses","schema":{"items":{"enum":["todo","in_progress","blocked","done","cancelled"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks with any of these priorities. A single value or a repeated `priorities` query param both work.","in":"query","name":"priorities","schema":{"items":{"enum":["urgent","high","medium","low"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks of any of these types. A single value or a repeated `types` query param both work.","in":"query","name":"types","schema":{"items":{"enum":["file","transaction","transactions","question","invite_accountant","receipt_phone_number","connection_broken","plaid_new_accounts_available","plaid_statements_refresh","map_chart_of_accounts","connect_account","map_migrated_data","profit_loss_activation","profit_loss","balance_sheet","general_ledger","trial_balance","expenses_by_vendor","cash_flow_statement","ar_aging_summary","ar_aging_detail","check_detail","form_1099_summary","form_1099_detail","document_retrieval","get_documents","accrual_review","reconciliation","file_migration_upload","transaction_review","form_1099","counterparties","bills","invoices","financial_documents","schedule_rule_suggested_review","schedule_suspicious_transaction_review","revenue_recognition_review","schedule_source_change_review","milestone_revenue_recognition_review","integration_coa_mapping","payroll_locked_period_correction","payroll_unmapped_items","fixed_asset_review","fixed_asset_account_mapping"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks in any of these task groups. A single value or a repeated `groupIds` query param both work.","in":"query","name":"groupIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks assigned to any of these entities of the workspace. A single value or a repeated `entityIds` query param both work. An entity outside the workspace is rejected.","in":"query","name":"entityIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks assigned to any of these users. Combined with `isUnassigned=true`, unassigned tasks are included too. A single value or a repeated `assigneeIds` query param both work.","in":"query","name":"assigneeIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"`true` keeps only tasks without an assignee (or, with `assigneeIds`, adds them). `false` keeps only assigned tasks.","in":"query","name":"isUnassigned","schema":{"enum":["true","false"],"type":"string"}},{"description":"Only tasks created by any of these users. A single value or a repeated `createdByIds` query param both work.","in":"query","name":"createdByIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks last marked as done by any of these users. A single value or a repeated `completedByIds` query param both work.","in":"query","name":"completedByIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only tasks due on or after this calendar day, as YYYY-MM-DD.","in":"query","name":"dueDateStart","schema":{"format":"date","type":"string"}},{"description":"Only tasks due on or before this calendar day, as YYYY-MM-DD.","in":"query","name":"dueDateEnd","schema":{"format":"date","type":"string"}},{"description":"Only tasks created on or after this calendar day in the workspace's timezone, as YYYY-MM-DD.","in":"query","name":"createdAtStart","schema":{"format":"date","type":"string"}},{"description":"Only tasks created on or before this calendar day in the workspace's timezone, as YYYY-MM-DD.","in":"query","name":"createdAtEnd","schema":{"format":"date","type":"string"}},{"description":"Only tasks last marked as done on or after this calendar day in the workspace's timezone, as YYYY-MM-DD.","in":"query","name":"completedAtStart","schema":{"format":"date","type":"string"}},{"description":"Only tasks last marked as done on or before this calendar day in the workspace's timezone, as YYYY-MM-DD.","in":"query","name":"completedAtEnd","schema":{"format":"date","type":"string"}},{"description":"Only tasks whose title contains this text (case-insensitive).","in":"query","name":"search","schema":{"maxLength":200,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"assignee":{"description":"The user referenced by `assigneeId`. Present only when `relations` includes `assignee`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"assigneeId":{"format":"uuid","nullable":true,"type":"string"},"completedAt":{"description":"When the task was last marked as done.","format":"date-time","nullable":true,"type":"string"},"completedBy":{"description":"The user referenced by `completedById`. Present only when `relations` includes `completedBy`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"completedById":{"description":"User who last marked the task as done.","format":"uuid","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"description":"The user referenced by `createdById`. Present only when `relations` includes `createdBy`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"createdById":{"format":"uuid","nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"dueDate":{"description":"Calendar day the task is due, as YYYY-MM-DD. Null when the task has no due date.","format":"date","nullable":true,"type":"string"},"entities":{"description":"The entities referenced by `entityIds`. Present only when `relations` includes `entities`.","items":{"properties":{"address":{"description":"Business address of the entity.","nullable":true,"properties":{"city":{"type":"string"},"country":{"description":"ISO country code. Always \"US\".","type":"string"},"postalCode":{"type":"string"},"state":{"description":"2-letter US state code, e.g. \"CA\".","nullable":true,"type":"string"},"street":{"type":"string"},"street2":{"nullable":true,"type":"string"}},"required":["street","street2","city","state","postalCode","country"],"type":"object"},"bookkeepingStartDate":{"description":"First day Kick keeps books for the entity, as YYYY-MM-DD.","format":"date","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Short description of what the business does.","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"industries":{"description":"Industries the business operates in.","items":{"enum":["accountant","agency","bookkeeper","construction","consulting","content","crypto","trucking","financial_advisor","investor","legal","manufacturing","medical","non_profit","physical_goods","property_management","psychologist","real_estate_agent","real_estate_investor","restaurant","retail","saas","tradeperson","entertainment","other"],"type":"string"},"type":"array"},"industryOther":{"description":"Free-text industry, typically used alongside the `other` industry.","nullable":true,"type":"string"},"legalType":{"enum":["sole_proprietorship","smllc","mmllc","s_corp","partnership","c_corp","no_legal_entity"],"nullable":true,"type":"string"},"logoUrl":{"description":"Public link to the entity logo. Read-only; the logo is managed in Kick.","nullable":true,"type":"string"},"metadata":{"additionalProperties":{"nullable":true},"description":"Free-form JSON object owned by the API client. Kick stores it as-is and never reads it.","type":"object"},"name":{"nullable":true,"type":"string"},"website":{"description":"Website of the business.","nullable":true,"type":"string"},"workspaceId":{"format":"uuid","type":"string"}},"required":["id","workspaceId","name","legalType","bookkeepingStartDate","description","website","industries","industryOther","address","logoUrl","metadata","createdAt"],"type":"object"},"type":"array"},"entityIds":{"description":"Entities of the workspace the task is assigned to.","items":{"format":"uuid","type":"string"},"type":"array"},"groupId":{"description":"Task group the task belongs to, null when ungrouped.","format":"uuid","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"metadata":{"description":"Extra details about the task. New fields may be added over time.","properties":{"transactionIds":{"description":"Transactions the task covers, by id. Deleted transactions and transactions outside the workspace are left out. Empty when a `transactions` or `transaction_review` task selects its transactions by other criteria or none of its transactions remain. Null for task types that don't reference transactions.","items":{"format":"uuid","type":"string"},"nullable":true,"type":"array"}},"required":["transactionIds"],"type":"object"},"priority":{"enum":["urgent","high","medium","low"],"nullable":true,"type":"string"},"status":{"enum":["todo","in_progress","blocked","done","cancelled"],"type":"string"},"title":{"type":"string"},"type":{"enum":["file","transaction","transactions","question","invite_accountant","receipt_phone_number","connection_broken","plaid_new_accounts_available","plaid_statements_refresh","map_chart_of_accounts","connect_account","map_migrated_data","profit_loss_activation","profit_loss","balance_sheet","general_ledger","trial_balance","expenses_by_vendor","cash_flow_statement","ar_aging_summary","ar_aging_detail","check_detail","form_1099_summary","form_1099_detail","document_retrieval","get_documents","accrual_review","reconciliation","file_migration_upload","transaction_review","form_1099","counterparties","bills","invoices","financial_documents","schedule_rule_suggested_review","schedule_suspicious_transaction_review","revenue_recognition_review","schedule_source_change_review","milestone_revenue_recognition_review","integration_coa_mapping","payroll_locked_period_correction","payroll_unmapped_items","fixed_asset_review","fixed_asset_account_mapping"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"workspaceId":{"format":"uuid","type":"string"}},"required":["id","workspaceId","title","description","status","priority","type","dueDate","groupId","entityIds","assigneeId","createdById","completedById","completedAt","createdAt","updatedAt","metadata"],"type":"object"},"type":"array"},"pagination":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"],"type":"object"}},"required":["data","pagination"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"List tasks","tags":["tasks"]}}}}
```

### Retrieve a task

Returns one task of the workspace, with the same `relations` options as the list. A task of another workspace, or one internal to another organization, answers `404`.

## Retrieve a task

> Returns a single task of the workspace. Pass \`relations=entities\` to include the assigned entities in \`entities\`, and \`relations=assignee\`, \`relations=createdBy\` or \`relations=completedBy\` to include the referenced users.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/workspaces/{workspaceId}/tasks/{taskId}":{"get":{"description":"Returns a single task of the workspace. Pass `relations=entities` to include the assigned entities in `entities`, and `relations=assignee`, `relations=createdBy` or `relations=completedBy` to include the referenced users.","operationId":"tasks.get","parameters":[{"in":"path","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Related data to include in the response: `entities`, `assignee`, `createdBy`, `completedBy`. A single value or a repeated `relations` query param both work. Relations that are not requested are left out of the response.","in":"query","name":"relations","schema":{"items":{"enum":["entities","assignee","createdBy","completedBy"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"task":{"properties":{"assignee":{"description":"The user referenced by `assigneeId`. Present only when `relations` includes `assignee`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"assigneeId":{"format":"uuid","nullable":true,"type":"string"},"completedAt":{"description":"When the task was last marked as done.","format":"date-time","nullable":true,"type":"string"},"completedBy":{"description":"The user referenced by `completedById`. Present only when `relations` includes `completedBy`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"completedById":{"description":"User who last marked the task as done.","format":"uuid","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"description":"The user referenced by `createdById`. Present only when `relations` includes `createdBy`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"createdById":{"format":"uuid","nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"dueDate":{"description":"Calendar day the task is due, as YYYY-MM-DD. Null when the task has no due date.","format":"date","nullable":true,"type":"string"},"entities":{"description":"The entities referenced by `entityIds`. Present only when `relations` includes `entities`.","items":{"properties":{"address":{"description":"Business address of the entity.","nullable":true,"properties":{"city":{"type":"string"},"country":{"description":"ISO country code. Always \"US\".","type":"string"},"postalCode":{"type":"string"},"state":{"description":"2-letter US state code, e.g. \"CA\".","nullable":true,"type":"string"},"street":{"type":"string"},"street2":{"nullable":true,"type":"string"}},"required":["street","street2","city","state","postalCode","country"],"type":"object"},"bookkeepingStartDate":{"description":"First day Kick keeps books for the entity, as YYYY-MM-DD.","format":"date","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"description":"Short description of what the business does.","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"industries":{"description":"Industries the business operates in.","items":{"enum":["accountant","agency","bookkeeper","construction","consulting","content","crypto","trucking","financial_advisor","investor","legal","manufacturing","medical","non_profit","physical_goods","property_management","psychologist","real_estate_agent","real_estate_investor","restaurant","retail","saas","tradeperson","entertainment","other"],"type":"string"},"type":"array"},"industryOther":{"description":"Free-text industry, typically used alongside the `other` industry.","nullable":true,"type":"string"},"legalType":{"enum":["sole_proprietorship","smllc","mmllc","s_corp","partnership","c_corp","no_legal_entity"],"nullable":true,"type":"string"},"logoUrl":{"description":"Public link to the entity logo. Read-only; the logo is managed in Kick.","nullable":true,"type":"string"},"metadata":{"additionalProperties":{"nullable":true},"description":"Free-form JSON object owned by the API client. Kick stores it as-is and never reads it.","type":"object"},"name":{"nullable":true,"type":"string"},"website":{"description":"Website of the business.","nullable":true,"type":"string"},"workspaceId":{"format":"uuid","type":"string"}},"required":["id","workspaceId","name","legalType","bookkeepingStartDate","description","website","industries","industryOther","address","logoUrl","metadata","createdAt"],"type":"object"},"type":"array"},"entityIds":{"description":"Entities of the workspace the task is assigned to.","items":{"format":"uuid","type":"string"},"type":"array"},"groupId":{"description":"Task group the task belongs to, null when ungrouped.","format":"uuid","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"metadata":{"description":"Extra details about the task. New fields may be added over time.","properties":{"transactionIds":{"description":"Transactions the task covers, by id. Deleted transactions and transactions outside the workspace are left out. Empty when a `transactions` or `transaction_review` task selects its transactions by other criteria or none of its transactions remain. Null for task types that don't reference transactions.","items":{"format":"uuid","type":"string"},"nullable":true,"type":"array"}},"required":["transactionIds"],"type":"object"},"priority":{"enum":["urgent","high","medium","low"],"nullable":true,"type":"string"},"status":{"enum":["todo","in_progress","blocked","done","cancelled"],"type":"string"},"title":{"type":"string"},"type":{"enum":["file","transaction","transactions","question","invite_accountant","receipt_phone_number","connection_broken","plaid_new_accounts_available","plaid_statements_refresh","map_chart_of_accounts","connect_account","map_migrated_data","profit_loss_activation","profit_loss","balance_sheet","general_ledger","trial_balance","expenses_by_vendor","cash_flow_statement","ar_aging_summary","ar_aging_detail","check_detail","form_1099_summary","form_1099_detail","document_retrieval","get_documents","accrual_review","reconciliation","file_migration_upload","transaction_review","form_1099","counterparties","bills","invoices","financial_documents","schedule_rule_suggested_review","schedule_suspicious_transaction_review","revenue_recognition_review","schedule_source_change_review","milestone_revenue_recognition_review","integration_coa_mapping","payroll_locked_period_correction","payroll_unmapped_items","fixed_asset_review","fixed_asset_account_mapping"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"workspaceId":{"format":"uuid","type":"string"}},"required":["id","workspaceId","title","description","status","priority","type","dueDate","groupId","entityIds","assigneeId","createdById","completedById","completedAt","createdAt","updatedAt","metadata"],"type":"object"}},"required":["task"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"Retrieve a task","tags":["tasks"]}}}}
```

### List task messages

Every task has a message thread, the conversation shown beside the task in Kick. This endpoint returns it oldest first, paged with `limit` and `offset`.

* `content` is plain text, one line per paragraph or list item.
* A reply in a sub-thread carries the message it answers in `parentMessageId`. Messages on the main timeline have `null` there.
* A deleted message stays in the list with `isDeleted: true` and `content: null`, so the replies under it keep their parent.
* `authorId` is `null` for messages Kick posted and for messages posted through this API. Pass `relations=author` to include the author's user record.
* `visibility` is `shared` for messages everyone working on the task sees, and `internal` for messages only your organization sees. Another organization's internal messages are left out.

## List task messages

> Returns the messages of the task's thread, oldest first, as plain text. Replies are included and point to the message they answer through \`parentMessageId\`. Deleted messages stay in the list with \`isDeleted: true\` and a null \`content\`. Results are paged with \`limit\`/\`offset\`. Pass \`relations=author\` to include the author in \`author\`.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/workspaces/{workspaceId}/tasks/{taskId}/messages":{"get":{"description":"Returns the messages of the task's thread, oldest first, as plain text. Replies are included and point to the message they answer through `parentMessageId`. Deleted messages stay in the list with `isDeleted: true` and a null `content`. Results are paged with `limit`/`offset`. Pass `relations=author` to include the author in `author`.","operationId":"tasks.listMessages","parameters":[{"in":"path","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","schema":{"default":100,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"nullable":true,"type":"integer"}},{"description":"Related data to include in the response: `author`. A single value or a repeated `relations` query param both work. Relations that are not requested are left out of the response.","in":"query","name":"relations","schema":{"items":{"enum":["author"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"author":{"description":"The user referenced by `authorId`. Present only when `relations` includes `author`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"authorId":{"description":"User who wrote the message. Null for system messages and messages posted through the Platform API.","format":"uuid","nullable":true,"type":"string"},"content":{"description":"Message text in plain text, one line per paragraph or list item. Null when the message is deleted.","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"isDeleted":{"type":"boolean"},"parentMessageId":{"description":"Message this one replies to. Null for messages on the main timeline of the task thread.","format":"uuid","nullable":true,"type":"string"},"taskId":{"format":"uuid","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"visibility":{"description":"`shared` messages are visible to everyone working on the task. `internal` messages are visible only to your organization.","enum":["shared","internal"],"type":"string"}},"required":["id","taskId","parentMessageId","authorId","content","visibility","isDeleted","createdAt","updatedAt"],"type":"object"},"type":"array"},"pagination":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"],"type":"object"}},"required":["data","pagination"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"List task messages","tags":["tasks"]}}}}
```

### Post a task message

Posts a plain-text message to the main timeline of the task's thread and answers `201` with the stored message.

* `content` is required, trimmed, and up to 10,000 characters. Line breaks are kept.
* `visibility` defaults to `shared`, which shows the message to everyone working on the task. `internal` shows it only to your organization.
* The message has no author (`authorId` is `null`). In Kick it appears under a Platform API label rather than a teammate's name.
* Posting sends [`task.commented`](https://docs.kick.co/api/webhooks/task-commented.md), so your own endpoint receives the message you posted. An `internal` message is sent only to your organization.

## Post a task message

> Posts a plain-text message to the main timeline of the task's thread. The message has no author (\`authorId\` is null) and shows in Kick under a Platform API label. Pass \`visibility: internal\` to show it only to your organization; the default \`shared\` shows it to everyone working on the task.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/workspaces/{workspaceId}/tasks/{taskId}/messages":{"post":{"description":"Posts a plain-text message to the main timeline of the task's thread. The message has no author (`authorId` is null) and shows in Kick under a Platform API label. Pass `visibility: internal` to show it only to your organization; the default `shared` shows it to everyone working on the task.","operationId":"tasks.createMessage","parameters":[{"in":"path","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"taskId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with `Idempotent-Replayed: true`) instead of executing again.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":255,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"content":{"description":"Plain-text message body, up to 10000 characters. Line breaks are kept.","maxLength":10000,"minLength":1,"type":"string"},"visibility":{"default":"shared","description":"`shared` (default) shows the message to everyone working on the task. `internal` shows it only to your organization.","enum":["shared","internal"],"type":"string"}},"required":["content"],"type":"object"}}},"description":"Body"},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"message":{"properties":{"author":{"description":"The user referenced by `authorId`. Present only when `relations` includes `author`.","nullable":true,"properties":{"email":{"nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"type":"string"}},"required":["id","email","name"],"type":"object"},"authorId":{"description":"User who wrote the message. Null for system messages and messages posted through the Platform API.","format":"uuid","nullable":true,"type":"string"},"content":{"description":"Message text in plain text, one line per paragraph or list item. Null when the message is deleted.","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"isDeleted":{"type":"boolean"},"parentMessageId":{"description":"Message this one replies to. Null for messages on the main timeline of the task thread.","format":"uuid","nullable":true,"type":"string"},"taskId":{"format":"uuid","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"visibility":{"description":"`shared` messages are visible to everyone working on the task. `internal` messages are visible only to your organization.","enum":["shared","internal"],"type":"string"}},"required":["id","taskId","parentMessageId","authorId","content","visibility","isDeleted","createdAt","updatedAt"],"type":"object"}},"required":["message"],"type":"object"}}},"description":"201"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"Post a task message","tags":["tasks"]}}}}
```

### Task groups

Task groups organize a workspace's tasks into sections, and each task's `groupId` points to one of them. Every group has a `scope` that says where it is defined:

| Scope          | Belongs to        | Listed for                               |
| -------------- | ----------------- | ---------------------------------------- |
| `global`       | Kick              | Every workspace                          |
| `workspace`    | This workspace    | This workspace only                      |
| `organization` | Your organization | Every workspace in your book of business |

`isSystem` is `true` for groups Kick manages rather than users.

#### List task groups

Groups come back sorted by name and are paged with `limit` and `offset`. See [Paging](https://docs.kick.co/api/readme.md#paging).

* `ids` and `scopes` take a single value or a repeated query param, and match any of the values given.
* `search` matches text in the name, case-insensitive.

```bash
curl "https://use.kick.co/api/platform/v1/workspaces/8d3a1b52-9f1d-4a7e-b0a1-2c5d6e7f8a90/task-groups?scopes=workspace&scopes=organization" \
  -H "Authorization: Bearer kick_org_..."
```

## List task groups

> Returns the task groups available to the workspace's tasks: global groups, groups of the workspace and groups of the token organization, sorted by name. Optional filters narrow the list by group (\`ids\`), \`scopes\` and name (\`search\`). Multi-choice filters accept a single or a repeated query param. Results are paged with \`limit\`/\`offset\`.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/workspaces/{workspaceId}/task-groups":{"get":{"description":"Returns the task groups available to the workspace's tasks: global groups, groups of the workspace and groups of the token organization, sorted by name. Optional filters narrow the list by group (`ids`), `scopes` and name (`search`). Multi-choice filters accept a single or a repeated query param. Results are paged with `limit`/`offset`.","operationId":"taskGroups.list","parameters":[{"in":"path","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","schema":{"default":100,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"nullable":true,"type":"integer"}},{"description":"Only these task groups. A single value or a repeated `ids` query param both work.","in":"query","name":"ids","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only task groups with any of these scopes. A single value or a repeated `scopes` query param both work.","in":"query","name":"scopes","schema":{"items":{"enum":["global","workspace","organization"],"type":"string"},"minItems":1,"nullable":true,"type":"array"}},{"description":"Only task groups whose name contains this text (case-insensitive).","in":"query","name":"search","schema":{"maxLength":200,"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"createdAt":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"isSystem":{"description":"Whether the group is managed by Kick rather than by users.","type":"boolean"},"name":{"type":"string"},"scope":{"description":"Where the group is defined: `global` groups are shared by every workspace, `workspace` groups belong to this workspace, and `organization` groups belong to the token organization.","enum":["global","workspace","organization"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","scope","isSystem","createdAt","updatedAt"],"type":"object"},"type":"array"},"pagination":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"],"type":"object"}},"required":["data","pagination"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"List task groups","tags":["taskGroups"]}}}}
```

### Webhooks

Task changes made in Kick, by a user or by Kick itself, reach your endpoint as events:

* [`task.created`](https://docs.kick.co/api/webhooks/task-created.md) when tasks are created.
* [`task.updated`](https://docs.kick.co/api/webhooks/task-updated.md) when a task's title, priority, due date, assignee, group, or entities change.
* [`task.status_changed`](https://docs.kick.co/api/webhooks/task-status-changed.md) when a task's status changes.
* [`task.commented`](https://docs.kick.co/api/webhooks/task-commented.md) when a message is posted to a task's thread.
* [`task.deleted`](https://docs.kick.co/api/webhooks/task-deleted.md) when tasks are deleted.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kick.co/api/api-reference/tasks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
