Skip to main content

Tasks

Tags: automation, tasks, workflows

Endpoints​

List​

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

Description:

Task execution and monitoring

List all 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. Use this endpoint to view all available tasks for management, monitoring, or selection purposes.

Query Parameters:

  • include_archived: Include archived tasks in results (optional, default: false)
  • workflow_id: Filter tasks by specific workflow ID (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)
  • sortBy (TaskSortField)
  • sortOrder (SortOrder)

Response: List of TaskResponse

Create​

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

Description:

Task execution and monitoring

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)
  • shortPrompt: Brief task summary (optional, string)
  • workflowId: Associated workflow ID (required, integer)
  • 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:

Response: See TaskResponse

Delete Task Id​

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

Description:

Task execution and monitoring

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)

Get Task Id​

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

Description:

Task execution and monitoring

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:

Task execution and monitoring

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)
  • shortPrompt: Updated brief task summary (string)
  • workflowId: Updated workflow association (integer)
  • 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:

Response: See TaskResponse

Update Archive​

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

Description:

Task execution and monitoring

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:

Task execution and monitoring

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:

Response: See TaskResponse

Update Unarchive​

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

Description:

Task execution and monitoring

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