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
- Human-in-the-loop workflows: Tag tasks as 'reviewed' after manual inspection
- Approval chains: Track 'pending_approval', 'approved', 'rejected' states
- Quality control: Flag suspicious outputs with 'requires_review' tag
- 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)
Header Parameters
Body Parameters
Array of tag operations to perform in a single atomic transaction. Each item specifies an 'add' or 'remove' operation for a specific task. Operations processed sequentially; all succeed or all fail together.
Batch benefits:
- Single database transaction for consistency
- Reduced network overhead (one request vs many)
- Atomic operations (no partial failures)
Mixed operations supported:
- Add tags to multiple t...
Show child attributes
Response
Response Attributes
Array of operation results in request array order. Each element corresponds to the tag operation at the same index in the request.
Response structure:
- Length: Always equals request.tags length
- Order: Preserves request order (response[i] is result of request.tags[i])
- Content: Each item contains 'status' field indicating operation outcome
Example mapping: Request: [add_tag1, remove_tag2, add_tag3] Response: [status1, status2...
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.