Guides

Task groups

Build ordered task flows, link them to assistants, and override task instructions per assistant.

A task group is a named, ordered sequence of tasks — a structured flow the assistant can follow (e.g. a booking flow: collect name, collect date, confirm). Task groups belong to your tenant; you link them to individual assistants, and can override a task's instructions for one assistant without touching the shared definition.

Method	Path	Purpose
GET	`/taskgroups`	List task groups (with nested ordered tasks)
GET	`/taskgroups/{id}`	Get one task group with its tasks
POST	`/taskgroups`	Create a task group
PATCH	`/taskgroups/{id}`	Update name/description
DELETE	`/taskgroups/{id}`	Soft-delete (cascades to its tasks)
GET	`/taskgroups/{id}/tasks`	List tasks, ordered by `order` ascending
POST	`/taskgroups/{id}/tasks`	Create a task
POST	`/taskgroups/{id}/tasks/reorder`	Bulk-reorder all tasks
PATCH	`/taskgroups/{id}/tasks/{taskId}`	Update a task
DELETE	`/taskgroups/{id}/tasks/{taskId}`	Soft-delete a task
GET	`/assistants/{id}/taskgroups`	List task groups linked to an assistant
POST	`/assistants/{id}/taskgroups`	Link a task group
DELETE	`/assistants/{id}/taskgroups/{taskgroupId}`	Unlink a task group
GET	`/assistants/{id}/tasks/overrides`	List the assistant's task instruction overrides
POST	`/assistants/{id}/tasks/{taskId}/override`	Set an instruction override
DELETE	`/assistants/{id}/tasks/{taskId}/override`	Remove an instruction override

Task-driven mode

Assistants have a taskDrivenMode boolean (set via POST /assistants or PATCH /assistants/{id}) that enables task-group-driven conversation flow.

Create a task group#

POST /taskgroups

Field	Type	Required	Description
`name`	string	Yes	Max 255 chars, must match `^[a-z0-9_]+$` (lowercase letters, digits, underscore)
`description`	string	Yes	What the flow is for

bash

curl -X POST https://core-api.heysadie.ai/taskgroups \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "table_booking",
    "description": "Collects everything needed to book a table."
  }'

PATCH /taskgroups/{id} updates name and/or description. DELETE /taskgroups/{id} soft-deletes the group and cascades to its tasks.

Add tasks#

POST /taskgroups/{id}/tasks

Field	Type	Required	Description
`order`	integer ≥ 0	Yes	Position in the flow
`name`	string	Yes	Max 255 chars
`description`	string	Yes	What the task achieves
`instructions`	string	Yes	How the assistant should perform the task
`outputs`	string[] \| null	No	Output keys the task produces — each must be a valid identifier (`^[A-Za-z_][A-Za-z0-9_]*$`)
`toolNames`	string[] \| null	No	Names of tools the task may use
`type`	string \| null	No	Free-form task type label, max 50 chars

Terminal

curl -X POST https://core-api.heysadie.ai/taskgroups/TASKGROUP_ID/tasks \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 0,
    "name": "Collect party size",
    "description": "Find out how many people the booking is for.",
    "instructions": "Ask the caller how many guests will be dining. Accept 1-20.",
    "outputs": ["party_size"]
  }'

PATCH /taskgroups/{id}/tasks/{taskId} takes the same fields, all optional. DELETE /taskgroups/{id}/tasks/{taskId} soft-deletes a single task.

Reorder tasks#

POST /taskgroups/{id}/tasks/reorder — bulk-reorders all tasks in the group in one call:

Terminal

curl -X POST https://core-api.heysadie.ai/taskgroups/TASKGROUP_ID/tasks/reorder \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": [
      { "taskId": "0195f1e2-...", "order": 0 },
      { "taskId": "0195f1e2-...", "order": 1 }
    ]
  }'

The response is the full re-ordered task list. GET /taskgroups/{id}/tasks always returns tasks ordered by order ascending.

Link a task group to an assistant#

bash

curl -X POST https://core-api.heysadie.ai/assistants/ASSISTANT_ID/taskgroups \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskgroupId": "TASKGROUP_ID" }'

GET /assistants/{id}/taskgroups lists the groups linked to that assistant.
DELETE /assistants/{id}/taskgroups/{taskgroupId} unlinks a group (the group itself is untouched).

Per-assistant task overrides#

When one assistant needs slightly different instructions for a shared task, set an instruction override instead of forking the task group:

Terminal

curl -X POST https://core-api.heysadie.ai/assistants/ASSISTANT_ID/tasks/TASK_ID/override \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instructionOverride": "For this venue, also ask whether the caller wants indoor or outdoor seating." }'

GET /assistants/{id}/tasks/overrides lists all overrides for the assistant's linked tasks.
DELETE /assistants/{id}/tasks/{taskId}/override removes the override, restoring the shared task's instructions.

Next steps#

Assistants — enable taskDrivenMode and manage the rest of the configuration.
Tools — the tools referenced by toolNames.

PreviousKnowledge base NextPhone numbers