Update Task

Update any task field, including archiving and accepting drafts.

PATCH /api/v1/tasks/{task_id}

cURL

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"
}'

Response

{
  "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": "[e-mail]"
  },
  "assigned_to": {
    "id": "11111111-2222-3333-4444-555555555555",
    "name": "Jane Doe",
    "email": "[e-mail]"
  },
  "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": "[e-mail]",
      "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"
}

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

title · string

Short summary of the work.

description · string

The primary instruction. Send null to clear it.

additional_context · string

Supplementary context; the description wins on conflict. Send null to clear it.

assigned_to · string (uuid)

Send null to unassign.

assigned_agent · string (uuid)

Send null to detach the agent.

assigned_team_id · string (uuid)

Send null to unassign the team.

matter_id · string (uuid)

Send null to unfile the task.

status · enum

not_started, in_progress, waiting_on_external or completed.

priority · enum

no_priority, urgent, high, medium or low.

complete_by · string

ISO 8601, e.g. “2026-03-22T17:00:00Z”. Send null to clear the due date.

tags · array

Replaces the whole tag list.

linked_items · array

Replaces the whole link list.

involved_people · array

Replaces the set of people involved in the task.

archived · boolean

Shelve (true) or restore (false) the task. Orthogonal to status — the task keeps its status.

draft · boolean

Accept a draft with false. Orthogonal to status. To reject a draft, DELETE the task.

cURL

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"
}'

Response

{
  "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": "[e-mail]"
  },
  "assigned_to": {
    "id": "11111111-2222-3333-4444-555555555555",
    "name": "Jane Doe",
    "email": "[e-mail]"
  },
  "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": "[e-mail]",
      "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"
}