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

# Update Task

> Update any task field, including archiving and accepting drafts.

Only the fields you send are changed, and `{}` does nothing.

An explicit `null` **clears** these fields: `description`, `additional_context`, `assigned_to`, `assigned_agent`, `assigned_team_id`, `complete_by`, `matter_id`. So `{"assigned_to": null}` unassigns the task. For every other field a `null` is ignored rather than applied — send a real value (an empty array to empty `tags` or `linked_items`).

State changes are fields rather than separate endpoints:

| To do this           | Send                           |
| -------------------- | ------------------------------ |
| Archive              | `{"archived": true}`           |
| Restore from archive | `{"archived": false}`          |
| Accept a draft       | `{"draft": false}`             |
| Reassign             | `{"assigned_to": "<user_id>"}` |
| Unassign             | `{"assigned_to": null}`        |

Archiving and drafting are orthogonal to `status`: an archived task keeps the status it had.

## Body parameters

<ParamField body="title" type="string">
  Short summary of the work.
</ParamField>

<ParamField body="description" type="string">
  The primary instruction. Send null to clear it.
</ParamField>

<ParamField body="additional_context" type="string">
  Supplementary context; the description wins on conflict. Send null to clear it.
</ParamField>

<ParamField body="assigned_to" type="string (uuid)">
  Send null to unassign.
</ParamField>

<ParamField body="assigned_agent" type="string (uuid)">
  Send null to detach the agent.
</ParamField>

<ParamField body="assigned_team_id" type="string (uuid)">
  Send null to unassign the team.
</ParamField>

<ParamField body="matter_id" type="string (uuid)">
  Send null to unfile the task.
</ParamField>

<ParamField body="status" type="enum">
  not\_started, in\_progress, waiting\_on\_external or completed.
</ParamField>

<ParamField body="priority" type="enum">
  no\_priority, urgent, high, medium or low.
</ParamField>

<ParamField body="complete_by" type="string">
  ISO 8601, e.g. "2026-03-22T17:00:00Z". Send null to clear the due date.
</ParamField>

<ParamField body="tags" type="array">
  Replaces the whole tag list.
</ParamField>

<ParamField body="linked_items" type="array">
  Replaces the whole link list.
</ParamField>

<ParamField body="involved_people" type="array">
  Replaces the set of people involved in the task.
</ParamField>

<ParamField body="archived" type="boolean">
  Shelve (true) or restore (false) the task. Orthogonal to status — the task keeps its status.
</ParamField>

<ParamField body="draft" type="boolean">
  Accept a draft with false. Orthogonal to status. To reject a draft, DELETE the task.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request PATCH 'https://api.wordsmith.ai/api/v1/tasks/9f8e7d6c-5b4a-3210-9876-543210fedcba' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "completed",
    "priority": "medium"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.wordsmith.ai/api/v1/tasks/9f8e7d6c-5b4a-3210-9876-543210fedcba", {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "status": "completed",
      "priority": "medium"
    }),
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.wordsmith.ai/api/v1/tasks/9f8e7d6c-5b4a-3210-9876-543210fedcba"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
  }
  payload = {
      "status": "completed",
      "priority": "medium"
  }

  response = requests.patch(url, headers=headers, json=payload)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
    "display_id": "#12",
    "task_number": 12,
    "title": "Review the Acme NDA",
    "description": "Check the indemnity and termination clauses.",
    "additional_context": "Counterparty has pushed back twice on liability caps.",
    "status": "completed",
    "priority": "medium",
    "team": {
      "id": "1a2b3c4d-5e6f-7081-9200-aabbccddeeff",
      "name": "Legal"
    },
    "creator": {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "assigned_to": {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "assigned_agent": null,
    "assigned_team": null,
    "matter": null,
    "complete_by": "2026-01-01T00:00:00Z",
    "tags": [
      "nda",
      "urgent"
    ],
    "visibility": "customer",
    "archived": false,
    "draft": false,
    "involved_people": [
      {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Jane Doe",
        "email": "jane@example.com",
        "role": "assignee",
        "access_level": "write"
      }
    ],
    "shared_teams": [],
    "linked_items": [],
    "input_files": [],
    "output_files": [],
    "created_at": "2025-12-31T00:00:00Z",
    "updated_at": "2025-12-31T01:00:00Z"
  }
  ```
</ResponseExample>