Update a task

PUT

/tasks/{task_gid}

Tasks

A specific, existing task can be updated by making a PUT request on the
URL for that task. Only the fields provided in the data block will be
updated; any unspecified fields will remain unchanged.

When using this method, it is best to specify only those fields you wish
to change, or else you may overwrite changes made by another user since
you last retrieved the task.

Returns the complete updated task record.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request PUT 'https://app.asana.com/api/1.0/tasks/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "name": "Buy catnip",
        "approval_status": "pending",
        "assignee_status": "upcoming",
        "completed": false,
        "completed_by": {
            "name": "Greg Sanchez"
        },
        "due_at": "2019-09-15T02:06:58.147Z",
        "due_on": "2019-09-15",
        "external": {
            "data": "A blob of information",
            "gid": "my_gid"
        },
        "html_notes": "<body>Mittens <em>really</em> likes the stuff from Humboldt.</body>",
        "liked": true,
        "notes": "Mittens really likes the stuff from Humboldt.",
        "resource_subtype": "default_task",
        "start_on": "2019-09-14",
        "assignee": "12345",
        "assignee_section": "12345",
        "custom_fields": {
            "4578152156": "Not Started",
            "5678904321": "On Hold"
        },
        "followers": [
            "12345"
        ],
        "parent": "12345",
        "projects": [
            "12345"
        ],
        "tags": [
            "12345"
        ],
        "workspace": "12345"
    }
}'

Response Example

200 - Example 1

{
  "data": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Buy catnip",
    "approval_status": "pending",
    "assignee_status": "upcoming",
    "completed": false,
    "completed_at": "2012-02-22T02:06:58.147Z",
    "completed_by": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    },
    "created_at": "2012-02-22T02:06:58.147Z",
    "dependencies": [
      {
        "gid": "12345",
        "resource_type": "task"
      }
    ],
    "dependents": [
      {
        "gid": "12345",
        "resource_type": "task"
      }
    ],
    "due_at": "2019-09-15T02:06:58.147Z",
    "due_on": "2019-09-15",
    "external": {
      "data": "A blob of information",
      "gid": "my_gid"
    },
    "hearted": true,
    "hearts": [
      {
        "gid": "12345",
        "user": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Greg Sanchez"
        }
      }
    ],
    "html_notes": "<body>Mittens <em>really</em> likes the stuff from Humboldt.</body>",
    "is_rendered_as_separator": false,
    "liked": true,
    "likes": [
      {
        "gid": "12345",
        "user": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Greg Sanchez"
        }
      }
    ],
    "memberships": [
      {
        "project": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Stuff to buy"
        },
        "section": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Next Actions"
        }
      }
    ],
    "modified_at": "2012-02-22T02:06:58.147Z",
    "notes": "Mittens really likes the stuff from Humboldt.",
    "num_hearts": 5,
    "num_likes": 5,
    "num_subtasks": 3,
    "resource_subtype": "default_task",
    "start_on": "2019-09-14",
    "assignee": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    },
    "assignee_section": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Next Actions"
    },
    "custom_fields": [
      {
        "gid": "12345",
        "resource_type": "task",
        "display_value": "blue",
        "enabled": true,
        "enum_options": [
          {
            "gid": "12345",
            "resource_type": "task",
            "color": "blue",
            "enabled": true,
            "name": "Low"
          }
        ],
        "name": "Status",
        "number_value": 5.2,
        "resource_subtype": "text",
        "text_value": "Some Value",
        "type": "text",
        "currency_code": "EUR",
        "custom_label": "gold pieces",
        "custom_label_position": "suffix",
        "description": "Development team priority",
        "format": "custom",
        "has_notifications_enabled": true,
        "is_global_to_workspace": true,
        "precision": 2,
        "created_by": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Greg Sanchez"
        },
        "enum_value": {
          "gid": "12345",
          "resource_type": "task",
          "color": "blue",
          "enabled": true,
          "name": "Low"
        },
        "multi_enum_values": [
          {
            "gid": "12345",
            "resource_type": "task",
            "color": "blue",
            "enabled": true,
            "name": "Low"
          }
        ]
      }
    ],
    "followers": [
      {
        "gid": "12345",
        "resource_type": "task",
        "name": "Greg Sanchez"
      }
    ],
    "parent": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Bug Task"
    },
    "permalink_url": "https://app.asana.com/0/resource/123456789/list",
    "projects": [
      {
        "gid": "12345",
        "resource_type": "task",
        "name": "Stuff to buy"
      }
    ],
    "tags": [
      {
        "gid": "59746",
        "name": "Grade A"
      }
    ],
    "workspace": {
      "gid": "12345",
      "resource_type": "task",
      "name": "My Company Workspace"
    }
  }
}

Request

Path Params

task_gid

string

required

Body Params application/json

data

object (TaskRequest)

optional

The task is the basic object around which many operations in Asana are centered.

assignee

string | null

optional

Gid of a user.

Example:

12345

assignee_section

string | null

optional

The assignee section is a subdivision of a project that groups tasks together in the assignee's "My Tasks" list. It can either be a header above a list of tasks in a list view or a column in a board view of "My Tasks."
The assignee_section property will be returned in the response only if the request was sent by the user who is the assignee of the task. Note that you can only write to assignee_section with the gid of an existing section visible in the user's "My Tasks" list.

Example:

12345

custom_fields

object

optional

An object where each key is a Custom Field gid and each value is an enum gid, string, or number.

Example:

{"4578152156":"Not Started","5678904321":"On Hold"}

followers

array[string]

optional

Create-Only An array of strings identifying users. These can either be the string "me", an email, or the gid of a user. In order to change followers on an existing task use addFollowers and removeFollowers.

Example:

["12345"]

parent

string | null

optional

Gid of a task.

Example:

12345

projects

array[string]

optional

Create-Only Array of project gids. In order to change projects on an existing task use addProject and removeProject.

Example:

["12345"]

tags

array[string]

optional

Create-Only Array of tag gids. In order to change tags on an existing task use addTag and removeTag.

Example:

["12345"]

workspace

string

optional

Gid of a workspace.

Example:

12345

approval_status

enum<string>

optional

Conditional Reflects the approval status of this task. This field is kept in sync with completed, meaning pending translates to false while approved, rejected, and changes_requested translate to true. If you set completed to true, this field will be set to approved.

Allowed values:

pendingapprovedrejectedchanges_requested

Example:

pending

assignee_status

enum<string>

optional

Deprecated Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to "inbox" or "upcoming" inserts it at the top of the section, while the other options will insert at the bottom.

Allowed values:

todayupcominglaternewinbox

Example:

upcoming

completed

boolean

optional

True if the task is currently marked complete, false if not.

Example:

false

completed_by

object

UserCompact

optional

A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.

due_at

string <date> | null

optional

The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with due_on.

Example:

2019-09-15T02:06:58.147Z

due_on

string <date> | null

optional

The localized date on which this task is due, or null if the task has no due date. This takes a date with YYYY-MM-DD format and should not be used together with due_at.

Example:

2019-09-15

external

object

optional

OAuth Required. Conditional. This field is returned only if external values are set or included by using [Opt In] (/docs/input-output-options).
The external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation external:custom_gid to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.

Example:

{"data":"A blob of information","gid":"my_gid"}

html_notes

string

optional

Opt In. The notes of the text with formatting as HTML.

Example:

<body>Mittens <em>really</em> likes the stuff from Humboldt.</body>

liked

boolean

optional

True if the task is liked by the authorized user, false if not.

Example:

true

name

string

optional

The name of the task.

Example:

null

notes

string

optional

Free-form textual information associated with the task (i.e. its description).

Example:

Mittens really likes the stuff from Humboldt.

resource_subtype

enum<string>

optional

The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
The resource_subtype milestone represent a single moment in time. This means tasks with this subtype cannot have a start_date.

Allowed values:

default_taskmilestonesectionapproval

Example:

default_task

start_on

string <date> | null

optional

The day on which work begins for the task , or null if the task has no start date. This takes a date with YYYY-MM-DD format.
Note: due_on or due_at must be present in the request when setting or unsetting the start_on parameter.

Example:

2019-09-14

Examples

Responses

🟢200Successfully updated the specified task.

application/json

Body

data

object (TaskResponse)

optional

The task is the basic object around which many operations in Asana are centered.

assignee

null | allOf {1}

optional

assignee_section

null | allOf {2}

optional

custom_fields

array[object (CustomFieldResponse) {21}]

read-onlyoptional

Array of custom field values applied to the task. These represent the custom field values recorded on this project for a particular custom field. For example, these custom field values will contain an enum_value property for custom fields of type enum, a text_value property for custom fields of type text, and so on. Please note that the gid returned on each custom field value is identical to the gid of the custom field, which allows referencing the custom field metadata through the /custom_fields/custom_field-gid endpoint.

followers

array[object (UserCompact) {3}]

read-onlyoptional

Array of users following this task.

parent

object

read-onlyoptional

The parent of this task, or null if this is not a subtask. This property cannot be modified using a PUT request but you can change it with the setParent endpoint. You can create subtasks by using the subtasks endpoint.

permalink_url

string

read-onlyoptional

A url that points directly to the object within Asana.

Example:

https://app.asana.com/0/resource/123456789/list

projects

array[object (ProjectCompact) {3}]

read-onlyoptional

Create-only. Array of projects this task is associated with. At task creation time, this array can be used to add the task to many projects at once. After task creation, these associations can be modified using the addProject and removeProject endpoints.