Tasks
Create task
Create a task, optionally assigned to a person, an agent or a team.
POST
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, or me for your API key’s user; 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. me added 2026-10-25.
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
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.
Chats, reviews, reports or other tasks to link. Each item takes
type, id, and optionally role and context, as in Link items.Create as a draft rather than a committed work item. Accept later with a PATCH of draft=false.