Add or remove task tags in batch

Add or remove tags from task executions in batch operations.

Overview Task tags provide flexible categorization and workflow state tracking for task executions. Tags enable custom workflows like review/approval processes, quality assurance, and business-specific categorization. This endpoint supports batch operations to efficiently add or remove multiple tags in a single request.

What are Task Tags? Task tags are key-value metadata attached to task executions for:

• Workflow state tracking: 'reviewed', 'approved', 'rejected'
• Quality assurance: 'quality_checked', 'flagged', 'verified'
• Custom categorization: 'priority_high', 'customer_vip', 'requires_attention'
• Audit trails: Track who reviewed what and when (via tag_metadata)

Batch Operations This endpoint accepts an array of tag operations in a single request:

• operation='add': Creates new tag (idempotent - returns 'already_exists' if duplicate)
• operation='remove': Soft-deletes tag (sets status='deleted')
• Mixed operations: Can add and remove different tags in same request
• Atomic processing: All operations succeed or all fail

Idempotency Adding an existing tag returns status='already_exists' without error. Removing a non-existent tag returns status='not_found' without error. This enables safe retries and prevents duplicate tag creation.

Soft Delete Behavior Tags are never hard-deleted. Removal sets status='deleted' and records:

• updated_at: Timestamp of deletion
• modified_by: User/service that performed deletion Soft-deleted tags are excluded from all list queries automatically.

Use Cases

1. Human-in-the-loop workflows: Tag tasks as 'reviewed' after manual inspection
2. Approval chains: Track 'pending_approval', 'approved', 'rejected' states
3. Quality control: Flag suspicious outputs with 'requires_review' tag
4. Custom business logic: Apply domain-specific tags for routing/filtering

Error Scenarios

• 404 Not Found: flow_execution_id doesn't exist or belongs to different organization
• 403 Forbidden: User lacks permission to modify tags in this organization
• 400 Bad Request: Invalid operation value or malformed request

Performance Notes Batch operations are optimized with a single database transaction. All tag additions/removals commit atomically. WebSocket notifications are sent after commit to notify connected clients of tag changes.

Related Endpoints

• GET /task-tags - List tags for a flow execution
• GET /task-executions - View task executions with their tags
• PUT /task-executions - Update task execution (separate from tagging)