Cross-matter task aggregation for steps, subtasks, and cross-workspace signoff requests. Supports listing, sharing, and bulk actions (reassign, branch). Tasks are a unified view over steps, subtasks, and cross-workspace signoff records.

Route Conventions

• All endpoints require authentication and appropriate workspace permissions.
• Mutation routes (POST) require a valid security token and validate JSON payloads.
• Bulk actions require ADMIN or OWNER org role.

Endpoints

List Tasks

Aggregates active steps, pending subtasks, and pending cross-workspace signoff tasks assigned to the current user (or all org members for ADMIN/OWNER scope). Returns a paginated, sorted, unified task list. When multi-workspace oversight is active, tasks include an origin workspace identifier.

GET /api/tasks?scope=my&status=active&priority=ALL&sort=dueDate&page=1&limit=25

Query Parameters

Response

{
  "tasks": [
    {
      "id": "clx...",
      "type": "step",
      "title": "Review application",
      "matterId": "clx...",
      "matterTitle": "ACME Onboarding",
      "matterNumber": "MAT-0012",
      "boardName": "Client Onboarding",
      "dueDate": "2026-03-01T00:00:00.000Z",
      "priority": "HIGH",
      "status": "ACTIVE",
      "assignedAt": "2026-02-20T10:00:00.000Z",
      "stepType": "APPROVAL",
      "stepId": null,
      "assignee": { "id": "...", "name": "Jane", "email": "jane@..." },
      "isOverdue": false,
      "workspaceId": "clx...",
      "workspaceName": "My Workspace",
      "crossWorkspaceTaskId": null
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 42, "pages": 2 },
  "summary": { "active": 30, "overdue": 3, "completed": 9, "total": 42 },
  "assignees": [],
  "boards": ["Client Onboarding", "Due Diligence"],
  "isOverseer": true
}

The type field is one of "step", "subtask", or "signoff". The stepId is null for steps, set to the step ID for subtasks. The crossWorkspaceTaskId is set for signoff tasks.

Bulk Actions

Perform bulk operations on selected tasks. Requires ADMIN or OWNER org role. Supports two actions: reassign and branch.

Reassign

Updates the assignedToId on each selected step or subtask. Logs an audit event per task and sends a notification to the target user.

POST /api/tasks/bulk
Content-Type: application/json

{
  "action": "reassign",
  "tasks": [
    { "id": "clx...", "type": "step", "matterId": "clx...", "stepId": null },
    { "id": "cly...", "type": "subtask", "matterId": "clx...", "stepId": "clz..." }
  ],
  "assignedToId": "usr_target_id",
  "reason": "Holiday cover"
}

{ "success": true, "action": "reassign", "updated": 2 }

Branch Task

Creates a review copy (subtask) for each selected task, assigned to the target user. The branch subtask has branchSourceId and branchSourceType set, linking it to the original. When the original step or subtask is completed, all linked branch subtasks are automatically completed (cascade).

POST /api/tasks/bulk
Content-Type: application/json

{
  "action": "branch",
  "tasks": [
    { "id": "clx...", "type": "step", "matterId": "clx...", "stepId": null }
  ],
  "assignedToId": "usr_reviewer_id"
}

{ "success": true, "action": "branch", "created": 1, "branchIds": ["clb..."] }

Request Body

Branch Cascade Completion

When a step or subtask is completed, any branch subtasks linked to it are automatically completed. This ensures review copies don't linger after the original work is done.

Branch Fields on Subtasks

Branch subtasks include two additional fields: