Skip to main content

Workspace.Workflows.Crud

Tags: automation, workflows

Endpoints​

Delete Workflow Id​

DELETE /api/v2/w/{workspace_uuid}/workflows/{workflow_id}

Description:

Workflow creation and management

Delete a workflow permanently.

Removes a workflow from the workspace. By default, workflows with tasks cannot be deleted. Set cascade=true to delete the workflow and all its associated tasks. Deletion requires workspace admin scope and workflow delete/admin authority.

Path Parameters:

  • workflow_id: Unique identifier of the workflow to delete (integer)

Query Parameters:

  • cascade: If true, deletes workflow and all associated tasks (boolean, default: false)

Response: Returns a success status object:

  • status: "success" string confirming deletion
  • deletedTaskCount: Number of tasks deleted (only when cascade=true)

Permissions: Requires workflows:admin and workflow delete/admin authority.

Error Responses:

  • 400 Bad Request: Workflow has existing tasks and cascade=false
  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks delete authority
  • 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

  • GET /workflows/{workflow_id}/deletion-preview - Preview what will be deleted
  • GET /workflows/{workflow_id} - Get workflow details before deletion
  • PUT /workflows/{workflow_id} - Update workflow instead of deleting
  • POST /workflows/{workflow_id}/clone - Clone workflow before deletion

Authorization: Requires workflows:admin scope

Parameters:

  • workflow_id (Integer)
  • cascade (Boolean)

Get Workflow Id​

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}

Description:

Workflow creation and management

Retrieve a specific workflow by its identifier.

Fetches complete workflow details including all associated tasks, configuration, and permissions. This endpoint accepts multiple identifier formats for flexibility: numeric ID or UUID. Use this when you need to view or edit a specific workflow's complete configuration.

Path Parameters:

  • workflow_id: Workflow identifier (can be integer ID or UUID string)

Response: Returns a WorkflowResponse object containing:

  • id: Unique workflow identifier (integer)
  • uuid: Universal unique identifier (UUID string)
  • name: Workflow display name (string)
  • description: Workflow purpose description (string, nullable)
  • ownerId: ID of the member who owns the workflow (integer)
  • agentId: ID of the associated agent member (integer, nullable)
  • startTaskId: ID of the start task for this workflow (integer, nullable)
  • tasks: Array of associated tasks (TaskResponse objects)
  • permissions: Object with use and edit boolean flags
  • createdAt: Creation timestamp (ISO 8601)
  • updatedAt: Last modification timestamp (ISO 8601)

Permissions: Requires valid workspace membership and "use" permission on the workflow. Members without appropriate permissions will receive a 403 error even if the workflow exists.

Error Responses:

  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks "use" permission on this workflow
  • 404 Not Found: Workflow with specified identifier does not exist

Related Endpoints:

  • GET /workflows - List all workflows
  • PUT /workflows/{workflow_id} - Update a workflow
  • DELETE /workflows/{workflow_id} - Delete a workflow

Authentication: Requires workspace member

Parameters:

  • workflow_id (String)

Response: See WorkflowResponse

Update Workflow Id​

PUT /api/v2/w/{workspace_uuid}/workflows/{workflow_id}

Description:

Workflow creation and management

Update an existing workflow's configuration.

Modifies workflow settings including name, description, associated agent, and default task. Use this endpoint to refine workflows as your business processes evolve or to update configuration after initial creation.

Path Parameters:

  • workflow_id: Unique identifier of the workflow to update (integer)

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

  • name: Updated workflow display name (string)
  • description: Updated workflow description (string)
  • prompt: Updated workflow-level instruction prompt (string, nullable)
  • ownerId: Updated owner member ID (integer)
  • agentId: Updated associated agent ID (integer)
  • startTaskId: Updated start task ID (integer, nullable)
  • defaultPhoneNumberId: Updated default phone number ID (integer, nullable)
  • defaultInboxId: Updated default inbox ID (integer, nullable)
  • posX: Workflow diagram X position (number, nullable)
  • posY: Workflow diagram Y position (number, nullable)
  • abilities: Replacement workflow-level abilities (array)
  • eventRules: Replacement workflow-level event rules (array)
  • memberRoleAccess: Replacement role access policy (array; requires admin permission)

Response: Returns a WorkflowResponse object with the updated workflow configuration, including all associated tasks and current permissions.

Permissions: Requires valid workspace membership and "edit" permission on the workflow. Only workflow owners or members with appropriate permissions can update.

Error Responses:

  • 400 Bad Request: Invalid request data or validation failure
  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks "edit" permission on this workflow
  • 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

  • GET /workflows/{workflow_id} - Get workflow details
  • DELETE /workflows/{workflow_id} - Delete a workflow
  • POST /workflows/{workflow_id}/clone - Clone a workflow

Authorization: Requires workflows:write scope

Parameters:

Response: See WorkflowResponse

Archive​

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/archive

Description:

Workflow creation and management

Archive a workflow.

Archives a workflow, hiding it from the default workflow list. Archived workflows cannot be used to create new assignments, but existing assignments remain accessible. Members with workflow edit authority can archive workflows.

Path Parameters:

  • workflow_id: Unique identifier of the workflow to archive (integer)

Response: Returns a success status object:

  • status: "success" string confirming archival

Permissions: Requires workflows:write and workflow edit authority.

Error Responses:

  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks workflow edit authority
  • 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

  • POST /workflows/{workflow_id}/unarchive - Unarchive a workflow
  • DELETE /workflows/{workflow_id} - Delete a workflow permanently

Authorization: Requires workflows:write scope

Parameters:

  • workflow_id (Integer)

Clone​

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/clone

Description:

Workflow creation and management

Clone a workflow with all tasks and associations.

Creates a complete copy of an existing workflow including all associated tasks, task configurations, and relationships. Use this endpoint to duplicate successful workflows for reuse, create variations, or establish templates from existing work. The cloned workflow becomes owned by the requesting member.

Path Parameters:

  • workflow_id: Unique identifier of the workflow to clone (integer)

Request Body: Contains cloning parameters:

  • name: Display name for the cloned workflow (required, string)

Response: Returns a WorkflowResponse object with the newly cloned workflow containing:

  • New unique identifiers (id and uuid)
  • Copied configuration and settings
  • Cloned tasks with preserved configurations
  • Permissions for the current member (as owner)

Permissions: Requires valid workspace membership with "use" permission on the source workflow and permission to create workflows in the workspace. The cloned workflow is owned by the member who performs the cloning operation.

Error Responses:

  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks "use" permission on source workflow or cannot create workflows
  • 404 Not Found: Workflow with specified ID does not exist
  • 409 Conflict: A workflow with the specified name already exists
  • 500 Internal Server Error: Failed to reload cloned workflow data

Related Endpoints:

  • GET /workflows/{workflow_id} - View workflow before cloning
  • POST /workflows - Create new workflow from scratch
  • POST /workflows/templates/{template_uuid}/create-workflow - Create from template

Authorization: Requires workflows:write scope

Parameters:

Response: See WorkflowResponse

Deletion Preview​

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/deletion-preview

Description:

Workflow creation and management

Preview what will be deleted/archived when deleting a workflow.

Returns information about all tasks that will be deleted along with the workflow, and whether there are any assignments associated with this workflow.

Path Parameters:

  • workflow_id: Unique identifier of the workflow (integer)

Response: Returns an object containing:

  • taskCount: Number of tasks that will be deleted (integer)
  • tasks: Array of task objects with id, name, and description
  • hasAssignments: Whether this workflow has any assignments (boolean)

Permissions: Requires valid workspace membership and "edit" permission on the workflow.

Error Responses:

  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks "edit" permission
  • 404 Not Found: Workflow with specified ID does not exist

Authentication: Requires workspace member

Parameters:

  • workflow_id (Integer)

Unarchive​

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/unarchive

Description:

Workflow creation and management

Unarchive a workflow.

Restores an archived workflow, making it visible in the default workflow list and available for creating new assignments. Members with workflow edit authority can unarchive workflows.

Path Parameters:

  • workflow_id: Unique identifier of the workflow to unarchive (integer)

Response: Returns a success status object:

  • status: "success" string confirming unarchival

Permissions: Requires workflows:write and workflow edit authority.

Error Responses:

  • 401 Unauthorized: Authentication required or invalid session
  • 403 Forbidden: User lacks workflow edit authority
  • 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

  • POST /workflows/{workflow_id}/archive - Archive a workflow
  • GET /workflows?archived=true - List archived workflows

Authorization: Requires workflows:write scope

Parameters:

  • workflow_id (Integer)