Tasks

Tags: automation, tasks, workflows

Task execution and monitoring

In the product: Workflows

Resources

Request and response models used by the endpoints on this page.

AbilityData

Field	Type	Required	Description
abilityType	String	✓	The ability type slug (e.g., 'oversight:supervisor')
celCondition	String		CEL condition for activation
config	Dict[str, Any]		Ability configuration
enabled	Boolean		Whether the ability is enabled (default: True)
uuid	String	✓	UUID for matching/creating abilities

Example:

{
  "uuid": "string",
  "abilityType": "string",
  "enabled": true
}

AbilityResponse

Field	Type	Required	Description
abilityType	String	✓
celCondition	String
config	Dict[str, Any]	✓
enabled	Boolean	✓
id	Integer	✓
uuid	String	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "abilityType": "string",
  "config": {},
  "enabled": false
}

ChildTaskResponse

Field	Type	Required	Description
autoNext	Boolean	✓
celCondition	String	✓
choicePrompt	String	✓
id	Integer	✓
order	Integer	✓
required	Boolean	✓
taskId	Integer	✓
taskName	String	✓
taskUuid	String	✓

Example:

{
  "id": 0,
  "taskId": 0,
  "taskName": "string",
  "taskUuid": "string",
  "choicePrompt": "string",
  "celCondition": "string",
  "order": 0,
  "autoNext": false,
  "required": false
}

CloneTaskRequest

Field	Type	Required	Description
name	String	✓
slug	String

Example:

{
  "name": "string"
}

CreateTaskRequest

Field	Type	Required	Description
abilities	Array<AbilityData> | null
celGuard	String
childTasks	Array<TaskAssociationRequest> | null
configuration	Object
description	String
eventRules	Array<EventRuleData> | null
isAdmin	Boolean		Default: False
name	String	✓
posX	Number
posY	Number
prompt	String
taskType	String
workflowId	WorkflowId
workflowRevisionId	WorkflowRevisionId

Example:

{
  "name": "string",
  "isAdmin": false
}

EventRuleData

Field	Type	Required	Description
actionParams	dict[str, Any]		Parameters for the action
actionType	<enum EventRuleActionType	✓	The action type to execute
active	Boolean		Whether the rule is active (default: True)
conditions	String		CEL condition expression for conditional execution
delay	Integer		Delay in seconds before executing the action (default: 0)
eventType	<enum EventRuleEventType	✓	The event type that triggers this rule
name	String		Display name for the rule
objectType	EventRuleObjectType		The object type this rule applies to (inferred from parent if not provided)
triggerParams	dict[str, Any]		Parameters for the trigger (e.g., webhook config)
uuid	String	✓	UUID for matching/creating event rules

Example:

{
  "uuid": "string",
  "eventType": null,
  "actionType": null,
  "active": true,
  "delay": 0
}

EventRuleResponse

Field	Type	Required	Description
actionParams	Dict[str, Any]	✓
actionSetLocked	Boolean		Default: False
actionType	<enum EventRuleActionType	✓
active	Boolean	✓
appConnectionId	Integer
calendarEventTypeId	Integer	✓
calendarId	Integer	✓
celBlockedAt	DateTime
conditions	String	✓
createdAt	DateTime	✓
dataTypeId	Integer	✓
dataTypeName	String
delay	Integer	✓
error	String	✓
errorMessage	String	✓
eventType	<enum EventRuleEventType	✓
failedAt	DateTime	✓
id	Integer	✓
journeyId	Integer
journeyStepId	Integer	✓
name	String	✓
objectType	<enum EventRuleObjectType	✓
order	Integer	✓
routineId	Integer	✓
taskId	Integer	✓
taskName	String
taskWorkflowId	Integer
triggerParams	Dict[str, Any]	✓
updatedAt	DateTime	✓
uuid	String	✓
workflowRevisionId	Integer	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "objectType": null,
  "name": "string",
  "eventType": null,
  "conditions": "string",
  "actionType": null,
  "actionParams": {},
  "triggerParams": {},
  "active": false,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "taskId": 0,
  "dataTypeId": 0,
  "routineId": 0,
  "workflowRevisionId": 0,
  "calendarId": 0,
  "calendarEventTypeId": 0,
  "journeyStepId": 0,
  "error": "string",
  "errorMessage": "string",
  "failedAt": "2024-01-01T00:00:00Z",
  "delay": 0,
  "order": 0,
  "actionSetLocked": false
}

TaskAssociationRequest

Field	Type	Required	Description
autoNext	Boolean	✓
celCondition	String
choicePrompt	String
order	Integer
required	Boolean	✓
taskId	Integer	✓

Example:

{
  "taskId": 0,
  "autoNext": false,
  "required": false
}

TaskResponse

Field	Type	Required	Description
abilities	Array<AbilityResponse>		Default: []
archived	Boolean	✓
celGuard	String
childTasks	Array<ChildTaskResponse>		Default: []
configuration	Object
createdAt	DateTime	✓
description	String	✓
enterRules	Array<EventRuleResponse>	✓
eventRules	Array<EventRuleResponse>		Default: []
id	Integer	✓
inheritedAbilities	Array<AbilityResponse>		Default: []
isAdmin	Boolean	✓
leaveRules	Array<EventRuleResponse>	✓
lineageUuid	String
name	String	✓
ownerId	Integer
permissions	Integer		Default: 0
posX	Number
posY	Number
prompt	String	✓
taskType	String	✓
updatedAt	DateTime	✓
uuid	String	✓
workflowId	WorkflowId
workflowRevisionId	WorkflowRevisionId

Example:

{
  "id": 0,
  "name": "string",
  "uuid": "string",
  "taskType": "string",
  "description": "string",
  "prompt": "string",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "archived": false,
  "isAdmin": false,
  "enterRules": [],
  "leaveRules": [],
  "childTasks": [],
  "permissions": 0,
  "abilities": [],
  "inheritedAbilities": [],
  "eventRules": []
}

UpdateTaskRequest

Field	Type	Required	Description
abilities	Array<AbilityData> | null
archived	Boolean
celGuard	String
childTasks	Array<TaskAssociationRequest> | null
configuration	Object
description	String
eventRules	Array<EventRuleData> | null
isAdmin	Boolean
name	String
ownerId	Integer
posX	Number
posY	Number
prompt	String
taskType	String
workflowId	WorkflowId
workflowRevisionId	WorkflowRevisionId

Example:

{}

Endpoints

• GET /api/v2/w/{workspace_uuid}/tasks - List
• POST /api/v2/w/{workspace_uuid}/tasks - Create
• DELETE /api/v2/w/{workspace_uuid}/tasks/{task_id} - Delete Task Id
• GET /api/v2/w/{workspace_uuid}/tasks/{task_id} - Get Task Id
• PUT /api/v2/w/{workspace_uuid}/tasks/{task_id} - Update Task Id
• PUT /api/v2/w/{workspace_uuid}/tasks/{task_id}/archive - Update Archive
• POST /api/v2/w/{workspace_uuid}/tasks/{task_id}/clone - Clone
• PUT /api/v2/w/{workspace_uuid}/tasks/{task_id}/unarchive - Update Unarchive

List

GET /api/v2/w/{workspace_uuid}/tasks

Description:

List current tasks accessible to the authenticated member.

Returns a collection of tasks that the member can access based on workspace management permissions. Tasks represent specific AI agent operations within workflows. Without a workflow filter, only tasks from active and draft workflow revisions are returned; immutable historical copies remain available through the explicit workflow_revision_id filter.

Query Parameters:

• include_archived: Include archived tasks in results (optional, default: false)
• workflow_id: Filter by STABLE workflow root id — resolves to that workflow's draft revision's tasks (optional, integer)
• workflow_revision_id: Filter by an explicit workflow revision id — used by the read-only published-revision view (optional, integer)

Response: Returns an array of TaskResponse objects, each containing complete task configuration, associated workflow information, child-task links, abilities, event rules, and enabled features.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can list all tasks.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission

Related Endpoints:

• GET /tasks/{task_id} - Get a specific task
• POST /tasks - Create a new task
• GET /workflows/{workflow_id} - Get tasks within a workflow

Authorization: Requires workflows:read scope

Parameters:

• include_archived (Boolean)
• workflow_id (Integer)
• workflow_revision_id (Integer)
• sortBy (TaskSortField)
• sortOrder (SortOrder)

Response: List of TaskResponse

---

Create

POST /api/v2/w/{workspace_uuid}/tasks

Description:

Create a new task in the workspace.

Creates a task with specified configuration including prompts, guards, child-task links, abilities, event rules, and workflow assignment. Tasks define specific AI agent behavior within a workflow.

Request Body: Contains task creation parameters including:

• name: Task display name (required, string)
• taskType: Task category/type (optional, string)
• configuration: Task-specific configuration (optional, object)
• description: Task purpose description (optional, string)
• prompt: Main instruction prompt for the AI agent (optional, string)
• workflowId: Stable Workflow root ID (WorkflowId; optional if workflowRevisionId is set)
• workflowRevisionId: Explicit revision pin (WorkflowRevisionId; optional if workflowId is set)
• isAdmin: Whether the task is admin-only (optional, boolean)
• childTasks: Child task associations and routing metadata (optional)
• celGuard: CEL condition for entering the task (optional, string)
• posX, posY: Workflow diagram position (optional, number)
• abilities: Task-scoped abilities (optional, array)
• eventRules: Task-scoped event rules (optional, array)

Response: Returns a TaskResponse object with the newly created task including all configuration, associations, and default settings.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can create tasks.

Error Responses:

• 400 Bad Request: Invalid request data or validation failure
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 500 Internal Server Error: Failed to create task

Related Endpoints:

• GET /tasks - List all tasks
• PUT /tasks/{task_id} - Update the created task
• POST /tasks/import - Import a task from export data

Authorization: Requires workflows:write scope

Parameters:

• request - See CreateTaskRequest

Response: See TaskResponse

---

Delete Task Id

DELETE /api/v2/w/{workspace_uuid}/tasks/{task_id}

Description:

Delete a task permanently.

Removes a task from the workspace. This operation is restricted to prevent accidental deletion of tasks with active assignments. Tasks with existing assignments cannot be deleted and must be archived instead. Use this endpoint carefully as deletion is permanent.

Path Parameters:

• id: Unique identifier of the task to delete (integer)

Response: Returns deletion confirmation:

• status: "deleted" string confirming successful deletion

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can delete tasks.

Error Responses:

• 400 Bad Request: Task is not archived (archive it first)
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 404 Not Found: Task with specified ID does not exist
• 409 Conflict: Task has active assignment references and cannot be deleted
• 500 Internal Server Error: Unexpected error during deletion

Related Endpoints:

• PUT /tasks/{task_id}/archive - Archive task instead of deleting
• GET /tasks/{task_id} - View task before deletion
• GET /tasks/{task_id}/export - Export task before deletion for backup

Authorization: Requires workflows:admin scope

Parameters:

• task_id (Integer)

Response: dict[str, str]

---

Get Task Id

GET /api/v2/w/{workspace_uuid}/tasks/{task_id}

Description:

Retrieve a specific task by its identifier.

Fetches complete task details including configuration, associated workflow, child-task links, abilities, event rules, and prompt templates. This endpoint accepts multiple identifier formats: numeric ID or UUID. Use this when you need detailed information about a specific task.

Path Parameters:

• id: Task identifier (can be integer ID or UUID string)

Response: Returns a TaskResponse object containing complete task configuration including prompts, guards, child-task links, abilities, event rules, workflow information, and feature settings.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can view task details.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 404 Not Found: Task not found or member lacks access
• 500 Internal Server Error: Failed to retrieve task data

Related Endpoints:

• GET /tasks - List all tasks
• PUT /tasks/{task_id} - Update a task
• DELETE /tasks/{task_id} - Delete a task

Authorization: Requires workflows:read scope

Parameters:

• task_id (String)

Response: See TaskResponse

---

Update Task Id

PUT /api/v2/w/{workspace_uuid}/tasks/{task_id}

Description:

Update an existing task's configuration.

Modifies task settings including prompts, guards, child-task links, abilities, event rules, and workflow assignment. Use this endpoint to refine task behavior, update AI instructions, or adjust automation as workflows evolve.

Path Parameters:

• id: Unique identifier of the task to update (integer)

Request Body: Contains task update parameters (all optional):

• name: Updated task display name (string)
• taskType: Updated task category/type (string)
• configuration: Updated task-specific configuration (object)
• description: Updated task description (string)
• prompt: Updated AI instruction prompt (string)
• workflowId: Move to a stable Workflow root (WorkflowId; resolves to its draft revision)
• workflowRevisionId: Move to an explicit revision pin (WorkflowRevisionId)
• isAdmin: Updated admin-only flag (boolean)
• childTasks: Replacement child task associations and routing metadata
• celGuard: Updated CEL condition for entering the task
• posX, posY: Updated workflow diagram position
• abilities: Replacement task-scoped abilities
• eventRules: Replacement task-scoped event rules

Response: Returns a TaskResponse object with the updated task configuration including all associations and current settings.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can update tasks.

Error Responses:

• 400 Bad Request: Invalid request data or validation failure
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 404 Not Found: Task with specified ID does not exist
• 500 Internal Server Error: Failed to update task

Related Endpoints:

• GET /tasks/{task_id} - View task before updating
• DELETE /tasks/{task_id} - Delete a task
• PUT /tasks/{task_id}/archive - Archive instead of updating

Authorization: Requires workflows:write scope

Parameters:

• task_id (Integer)
• request - See UpdateTaskRequest

Response: See TaskResponse

---

Update Archive

PUT /api/v2/w/{workspace_uuid}/tasks/{task_id}/archive

Description:

Archive a task to hide it from active lists.

Marks a task as archived, removing it from default task listings while preserving all data and history. Archived tasks cannot be selected for new assignments but existing assignments remain functional. Use this instead of deletion to maintain historical data while decluttering active task lists.

Path Parameters:

• id: Unique identifier of the task to archive (integer)

Response: Returns a TaskResponse object with the archived task showing updated status and all preserved configuration.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can archive tasks.

Error Responses:

• 400 Bad Request: Task is set as default task for a workflow (must be changed first)
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 404 Not Found: Task with specified ID does not exist
• 500 Internal Server Error: Archiving operation failed

Related Endpoints:

• PUT /tasks/{task_id}/unarchive - Restore archived task
• GET /tasks?include_archived=true - List including archived tasks
• DELETE /tasks/{task_id} - Permanently delete a task

Authorization: Requires workflows:write scope

Parameters:

• task_id (Integer)

Response: See TaskResponse

---

Clone

POST /api/v2/w/{workspace_uuid}/tasks/{task_id}/clone

Description:

Clone an existing task with all its dependencies including abilities.

Creates a complete copy of a task including:

• Task configuration (prompts, settings, etc.)
• Data type associations
• File associations
• Child task relationships
• Event rules
• Abilities (task-scoped integration settings)

The cloned task will be created with a new name and optionally a new slug. All dependencies will be mapped to existing resources in the workspace.

Path Parameters:

• id: Unique identifier of the task to clone (integer)

Request Body:

• name: Name for the cloned task (required)
• slug: URL-friendly identifier for the cloned task (optional, auto-generated if not provided)

Response: Returns a TaskResponse object containing the newly created cloned task.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can clone tasks.

Error Responses:

• 400 Bad Request: Invalid request data or cloning failed
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 404 Not Found: Task not found or member lacks access
• 500 Internal Server Error: Clone operation failed

Related Endpoints:

• GET /tasks/{task_id}/export - Export a task for transfer to another workspace
• POST /tasks/import - Import a task from export data
• POST /tasks - Create a new task from scratch

Authorization: Requires workflows:write scope

Parameters:

• task_id (Integer)
• request - See CloneTaskRequest

Response: See TaskResponse

---

Update Unarchive

PUT /api/v2/w/{workspace_uuid}/tasks/{task_id}/unarchive

Description:

Restore an archived task to active status.

Unarchives a previously archived task, making it visible in default task listings and available for new assignments. All task configuration and history are preserved during archiving. Use this endpoint to reactivate tasks that were temporarily hidden.

Path Parameters:

• id: Unique identifier of the task to unarchive (integer)

Response: Returns a TaskResponse object with the restored task showing active status and all preserved configuration.

Permissions: Requires valid workspace membership with manage_workspace permission. Only workspace managers can unarchive tasks.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks manage_workspace permission
• 404 Not Found: Task with specified ID does not exist
• 500 Internal Server Error: Unarchiving operation failed

Related Endpoints:

• PUT /tasks/{task_id}/archive - Archive a task again
• GET /tasks - List active tasks (now includes unarchived task)
• PUT /tasks/{task_id} - Update unarchived task configuration

Authorization: Requires workflows:write scope

Parameters:

• task_id (Integer)

Response: See TaskResponse

---