> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarca.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Update task

> Updates one or more fields of a task. Only the fields you include are changed.

<Info>
  Requires the `tasks:write` scope. Viewers cannot edit tasks. Access-restricted
  members receive `403` if the task belongs to, or is being moved to, a list
  outside their permitted scope.
</Info>

## Path parameters

<ParamField path="id" type="string" required>
  The numeric task ID.
</ParamField>

## Request body

All fields are optional. Send only the fields you want to update.

<ParamField body="title" type="string">
  New task title. Cannot be set to an empty string.
</ParamField>

<ParamField body="description" type="string">
  Task description as an HTML string.
</ParamField>

<ParamField body="priority" type="string">
  Task priority. Must be one of `urgent`, `high`, `medium`, `low`, or `none`.
</ParamField>

<ParamField body="status_id" type="string">
  Numeric ID of a workspace status to apply. The status must belong to the same
  workspace.
</ParamField>

<ParamField body="list_id" type="string">
  Numeric ID of a list to move the task into. The list must belong to the same
  workspace.
</ParamField>

<ParamField body="due_date" type="string | null">
  Due date in ISO 8601 UTC format (e.g., `"2026-03-30T17:00:00Z"`). Pass `null` or an empty string to remove the due date.
</ParamField>

<ParamField body="start_date" type="string | null">
  Start date in ISO 8601 UTC format. Pass `null` or an empty string to remove the start date.
</ParamField>

<ParamField body="assignee_ids" type="array">
  Array of numeric user IDs to assign to the task. Replaces the current
  assignees entirely. Pass an empty array to remove all assignees. Omit this
  field to leave the current assignees unchanged. All IDs must be members of the
  same workspace; non-member IDs are silently ignored.
</ParamField>

<ParamField body="custom_fields" type="array">
  Optional array of custom field values to update. Each entry must contain a numeric `id` and a string `value` (or `null` to clear that field's value). Omitting this field entirely leaves all custom field values unchanged. Only fields that apply to the task's list and are visible to the API key user are processed; other fields are silently ignored.

  ```json theme={null}
  "custom_fields": [
    { "id": 1, "value": "Starter" },
    { "id": 2, "value": null }
  ]
  ```
</ParamField>

## Response

Returns the full updated task including its current assignees.

<ResponseField name="id" type="number" required>
  Task identifier.
</ResponseField>

<ResponseField name="workspace_id" type="number" required>
  Workspace this task belongs to.
</ResponseField>

<ResponseField name="list_id" type="number | null">
  List this task belongs to.
</ResponseField>

<ResponseField name="title" type="string" required>
  Task title.
</ResponseField>

<ResponseField name="description" type="string | null">
  Task description.
</ResponseField>

<ResponseField name="priority" type="string" required>
  Task priority.
</ResponseField>

<ResponseField name="identifier" type="number" required>
  Workspace-scoped sequential task number.
</ResponseField>

<ResponseField name="due_date" type="string | null">
  UTC ISO-8601 due date.
</ResponseField>

<ResponseField name="start_date" type="string | null">
  UTC ISO-8601 start date.
</ResponseField>

<ResponseField name="creator_id" type="number" required>
  User ID of the task creator.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  UTC ISO-8601 creation timestamp.
</ResponseField>

<ResponseField name="status" type="object | null">
  Current task status.

  <Expandable title="Status fields">
    <ResponseField name="id" type="number" required>Status identifier.</ResponseField>
    <ResponseField name="name" type="string" required>Status label.</ResponseField>
    <ResponseField name="icon" type="string | null">Icon.</ResponseField>
    <ResponseField name="color" type="string | null">Color.</ResponseField>
    <ResponseField name="category" type="string" required>One of `pending`, `in_progress`, `completed`, or `cancelled`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="assignees" type="array" required>
  Current assignees. Empty array if unassigned.

  <Expandable title="Assignee fields">
    <ResponseField name="id" type="number" required>User ID.</ResponseField>
    <ResponseField name="name" type="string" required>Display name.</ResponseField>
    <ResponseField name="avatar_url" type="string | null">Profile picture URL.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="custom_fields" type="array" required>
  Custom fields that apply to the task's list, each with its current value after the update.
  Fields the user does not have access to are not returned.

  <Expandable title="Custom field entry">
    <ResponseField name="id" type="number" required>Custom field identifier.</ResponseField>
    <ResponseField name="name" type="string" required>Custom field name (e.g., `"Customer Tier"`).</ResponseField>

    <ResponseField name="type" type="string" required>
      Field type. One of `text`, `number`, `date`, `checkbox`, `rating`, `dropdown`, `money`, or `people`.
    </ResponseField>

    <ResponseField name="config" type="object | null">
      Type-specific configuration.

      For example:

      * `rating` fields include `icon` and `color`;
      * `dropdown` fields include an `options` array of strings;
      * `money` fields include `currency` and `decimals`.

      It's `null` for field types with no configuration (which are `text`, `number`, `date`, `checkbox` and `people`).
    </ResponseField>

    <ResponseField name="position" type="number" required>Sort position of the field within the workspace.</ResponseField>

    <ResponseField name="value" type="string | null">
      The task's value for this field. `null` when no value has been set.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": 110,
    "workspace_id": 3,
    "list_id": 20,
    "title": "Write unit tests",
    "description": "<p>Cover all service layer methods.</p>",
    "priority": "urgent",
    "identifier": 14,
    "due_date": "2026-03-22T09:00:00.000Z",
    "start_date": null,
    "creator_id": 1,
    "created_at": "2026-03-18T18:00:00.000Z",
    "status": {
      "id": 1,
      "name": "To Do",
      "icon": "todo",
      "color": "gray",
      "category": "pending"
    },
    "assignees": [
      {
        "id": 7,
        "name": "Alice",
        "avatar_url": null
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "name": "Customer Tier",
        "type": "dropdown",
        "config": { "options": ["Free", "Starter", "Pro"] },
        "position": 1,
        "value": "Starter"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Invalid priority. Must be one of: urgent, high, medium, low, none"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Scope 'tasks:write' is required for this endpoint"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Task not found"
  }
  ```
</ResponseExample>