---
title: "Update a task"
method: PATCH
path: "/public-api/v1/tasks/{uuid}"
tags: ["Tasks"]
---

# Update a task

`PATCH /public-api/v1/tasks/{uuid}`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/tasks/{uuid}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hellobonsai.com/oauth/authorize`
    - Token URL: `https://app.hellobonsai.com/oauth/token`
  - HTTP bearer

Updates a task. Every field is optional, and anything you leave out keeps
its current value.

Send `task_status_id` to move the task to another column of your board —
that is how you mark it done. Sending `null` clears `due_date`,
`start_date`, `description`, `time_estimate_in_minutes`, `project_id`,
`deal_id` and `assignee_member_id`; `title` and `priority` cannot be
cleared this way.

A task the token cannot see returns `404`, and one it can see but may not
change returns `403`.

## Path parameters

- `uuid` string, required

## Request body

- object
  - `task` object, required
    - `title` string: New task title. A task must have one, so it cannot be blank.
    - `project_id` integer, nullable: Move the task to another project, or send `null` to detach it from the one it is on. Find one with `GET /public-api/v1/projects`.
    - `deal_id` integer, nullable: Move the task to another deal, or send `null` to take it off the one it is on. Independent of `project_id`. Needs permission to create deals; without it the request fails with `422 not_accessible`. A deal that is not in your account fails the same way. Find one with `GET /public-api/v1/deals`.
    - `assignee_member_id` union: Who the task is for: a team member id, or `me` for whoever the token belongs to. Send `null` to unassign it. Find ids with `GET /public-api/v1/team_members` — use the `company_member_id` field.
      - integer, nullable: Team member id of the assignee.
      - 'me': Assigns the task to whoever the token belongs to.
    - `priority` 'urgent' | 'high' | 'medium' | 'low': How urgent the task is. Can be changed but not cleared once set.
    - `due_date` string, date, nullable: Date the task is due. Send `null` to clear it.
    - `start_date` string, date, nullable: Date work on the task starts. Send `null` to clear it.
    - `description` string, nullable: What the task involves, as an HTML fragment. Send `null` to clear it. Read it back as `description_html` or `description_plain_text`.
    - `time_estimate_in_minutes` integer, nullable: Estimated effort in whole minutes. Must be positive, or `null` to clear it.
    - `task_status_id` string: Id of the board column to move the task to. Find one with `GET /public-api/v1/task_statuses`.
    - `billable` boolean: Whether time tracked on the task is billable. Sent alongside `project_id`, your value wins over the new project's default; left out, moving the task to another project re-derives it from that project. Only honoured for a token allowed to set billing, on a plan that includes task billing — otherwise the value is ignored. Check `permissions.tasks.billing_update` from `GET /public-api/v1/permissions/me` before relying on it.
    - `tag_ids` integer[]: The tags on the task, replacing whatever is there now. Send an empty array to remove them all. Must be `task` tags from your account — find them with `GET /public-api/v1/company_tags`.

## Response `200`

The task was updated.

- object
  - `data` object, required: The description fields returned when you retrieve a single task, but never in a list.
    - `uuid` string, uuid, nullable, required: Unique identifier for the task. This is the id every task endpoint takes in its path.
    - `title` string, nullable, required: Task title.
    - `number` string, nullable, required: Human-readable task reference. `null` until one has been assigned.
    - `due_date` string, date, nullable, required: Date the task is due, or `null` when it is unscheduled.
    - `start_date` string, date, nullable, required: Date work on the task starts, or `null` when unset.
    - `time_estimate_in_minutes` integer, nullable, required: Estimated effort in whole minutes, or `null` when no estimate is set.
    - `priority` 'urgent' | 'high' | 'medium' | 'low' | 'null', nullable, required: Priority bucket, or `null` when the task has no priority.
    - `completed_at` string, date-time, nullable, required: When the task was marked complete, or `null` while it is still open.
    - `archived_at` string, date-time, nullable, required: When the task was archived, or `null` while it is active.
    - `assignee_id` integer, nullable, required: User id of the assignee, or `null` when unassigned. Read-only — the create and update endpoints take `assignee_member_id` instead.
    - `assignee_member_id` integer, nullable, required: Team member id of the assignee, or `null` when unassigned. This is the value the create and update endpoints accept.
    - `creator_member_id` integer, nullable, required: Team member id of whoever created the task.
    - `project_id` integer, nullable, required: Id of the project the task belongs to, or `null` for a task that stands on its own.
    - `billable` boolean, nullable: Whether time logged against this task can be billed to the client. Absent unless the token is allowed to see billing.
    - `deal_id` integer, nullable: Id of the deal the task belongs to, or `null` when it is not attached to a deal. Absent unless the token is allowed to see deals.
    - `parent_task_uuid` string, nullable, required: `uuid` of this task's parent when it is a subtask, `null` for a top-level task.
    - `project_title` string, nullable, required: Title of the project the task belongs to, or `null`.
    - `assignee_member_name` string, nullable, required: Name of the assignee, or `null` when the task is unassigned.
    - `url` string, required: Absolute link to the task in the Bonsai app. Resolves to the task on its project board, or to the standalone task list when it belongs to no project.
    - `task_status` TaskStatus, required: A column of your task board. Moving a task between statuses is how you track its progress.
      - `id` string, uuid, required: Unique identifier for the status. Pass this value as `task_status_id` when creating or updating a task.
      - `status` string, required: Status name as it appears on the board.
      - `state` 'active' | 'complete', required: Whether tasks in this status count as open (`active`) or finished (`complete`).
      - `color` string, nullable, required: Hex color the status is drawn in, or `null` when it has none.
      - `position` integer, required: Position of the status on the board, ordered left to right.
    - `company_tags` CompanyTag[], required: Tags applied to the task. Only `id` and `name` are returned here — list the tags endpoint for a tag's type and color.
      - `id` integer, required: Unique identifier for the tag. Pass this value in `tag_ids` when tagging a task.
      - `name` string, required: Tag name as it appears in Bonsai.
    - `description_html` string, nullable, required: Task description as an HTML fragment, sanitized to a safe set of tags. Returned on single-task responses only, never in a list.
    - `description_plain_text` string, nullable, required: Task description with all HTML removed. Returned on single-task responses only, never in a list.
  - `meta` Meta, required: Metadata returned alongside every single-resource response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.

## Other responses

- `400`: The request body is missing its `task` wrapper.
- `401`: The access token is missing, expired or invalid.
- `403`: This token can see the task but is not allowed to change it.
- `404`: No task with that `uuid` that this token can see. Deleted and template tasks return `404` too.
- `422`: The task could not be saved. `blank` or `invalid_value` means a field was empty or the wrong shape; `not_accessible` means a referenced record is not in your account, or that this token is not allowed to set that particular field — `priority`, `due_date`, `start_date`, `time_estimate_in_minutes` and `assignee_member_id` all need permission to edit task details, and `deal_id` needs permission to create deals on top of that.
- `429`: Rate limit exceeded. Wait at least `Retry-After` seconds before trying again.

---

[API](https://skmtc.dev/hellobonsai/apis/bonsai-api.md) - [All operations](https://skmtc.dev/hellobonsai/apis/bonsai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hellobonsai/apis/bonsai-api/revisions/abf12ed6a8d3?raw)