Create Task

Create a task, optionally assigned to a person, an agent or a team.

POST /api/v1/tasks

cURL

curl --location --request POST 'https://api.wordsmith.ai/api/v1/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "title": "Review the Acme NDA",
  "description": "Check the indemnity and termination clauses.",
  "priority": "high",
  "assigned_to": "11111111-2222-3333-4444-555555555555",
  "complete_by": "2026-01-01T00:00:00Z",
  "tags": [
    "nda",
    "urgent"
  ]
}'

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": "in_progress",
  "priority": "high",
  "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": {
    "id": "66666666-6666-4666-8666-666666666666",
    "counsel_id": "77777777-7777-4777-8777-777777777777",
    "name": "Paralegal"
  },
  "assigned_team": null,
  "matter": null,
  "complete_by": "2026-01-01T00:00:00Z",
  "tags": [
    "nda",
    "urgent"
  ],
  "source_channel": "web",
  "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"
}

assigned_to and assigned_agent are independent — a task can carry both a human owner and an executing agent. Set draft: true to stage a task for review; accept it later by patching draft to false.

People, agents and teams can be referenced by id or by name: a person by user id, email address or name; an agent by its id, name or shortcut; a team by id or name. A reference that matches more than one record is rejected with a 400 that lists the candidates, so pass the id to disambiguate.

In the response, assigned_agent.id is the agent’s record id and assigned_agent.counsel_id is the agent id List Agents returns; either is accepted wherever an agent is referenced. counsel_id added 2026-09-05.

Tasks are created in your organization’s default task team. Choosing a different team, and creating a task as private, are not supported in v1.

Body parameters

title · string · required

Short summary of the work to be done.

description · string

The primary instruction for whoever picks the task up.

parent_task_id · string (uuid)

Create this task as a subtask of another task.

assigned_to · string

Person responsible for the task: a user id, email address, or name.

assigned_agent · string

Agent that should execute the task: an agent id, the agent’s name, or its shortcut. Independent of assigned_to — a task may have both.

assigned_team_id · string

Team the task is assigned to: a team id or team name. Grants that team editor access.

matter_id · string (uuid)

Matter to file the task under.

status · enum

Initial status. Defaults to the team’s first status.

priority · enum

Task priority.

complete_by · string

Due date as an ISO 8601 timestamp, e.g. “2026-03-22T17:00:00Z”.

tags · array

Free-form labels.

linked_items · array

Chats, reviews, reports or other tasks to link.

draft · boolean

Create as a draft rather than a committed work item. Accept later with a PATCH of draft=false.

cURL

curl --location --request POST 'https://api.wordsmith.ai/api/v1/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "title": "Review the Acme NDA",
  "description": "Check the indemnity and termination clauses.",
  "priority": "high",
  "assigned_to": "11111111-2222-3333-4444-555555555555",
  "complete_by": "2026-01-01T00:00:00Z",
  "tags": [
    "nda",
    "urgent"
  ]
}'

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": "in_progress",
  "priority": "high",
  "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": {
    "id": "66666666-6666-4666-8666-666666666666",
    "counsel_id": "77777777-7777-4777-8777-777777777777",
    "name": "Paralegal"
  },
  "assigned_team": null,
  "matter": null,
  "complete_by": "2026-01-01T00:00:00Z",
  "tags": [
    "nda",
    "urgent"
  ],
  "source_channel": "web",
  "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"
}