Add or remove task tags in batch
curl --request PATCH \
--url https://flows.super.ai/api/task-tags \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tags": [
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "add",
"tag": "reviewed",
"tag_metadata": {
"reviewer": "user@example.com"
},
"tag_type": "review_status",
"task_name": "extract_data"
},
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "remove",
"tag": "pending_review",
"tag_type": "review_status",
"task_name": "extract_data"
}
]
}
'import requests
url = "https://flows.super.ai/api/task-tags"
payload = { "tags": [
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "add",
"tag": "reviewed",
"tag_metadata": { "reviewer": "user@example.com" },
"tag_type": "review_status",
"task_name": "extract_data"
},
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "remove",
"tag": "pending_review",
"tag_type": "review_status",
"task_name": "extract_data"
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
tags: [
{
flow_execution_id: '123e4567-e89b-12d3-a456-426614174000',
operation: 'add',
tag: 'reviewed',
tag_metadata: {reviewer: 'user@example.com'},
tag_type: 'review_status',
task_name: 'extract_data'
},
{
flow_execution_id: '123e4567-e89b-12d3-a456-426614174000',
operation: 'remove',
tag: 'pending_review',
tag_type: 'review_status',
task_name: 'extract_data'
}
]
})
};
fetch('https://flows.super.ai/api/task-tags', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://flows.super.ai/api/task-tags",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'tags' => [
[
'flow_execution_id' => '123e4567-e89b-12d3-a456-426614174000',
'operation' => 'add',
'tag' => 'reviewed',
'tag_metadata' => [
'reviewer' => 'user@example.com'
],
'tag_type' => 'review_status',
'task_name' => 'extract_data'
],
[
'flow_execution_id' => '123e4567-e89b-12d3-a456-426614174000',
'operation' => 'remove',
'tag' => 'pending_review',
'tag_type' => 'review_status',
'task_name' => 'extract_data'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://flows.super.ai/api/task-tags"
payload := strings.NewReader("{\n \"tags\": [\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"add\",\n \"tag\": \"reviewed\",\n \"tag_metadata\": {\n \"reviewer\": \"user@example.com\"\n },\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n },\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"remove\",\n \"tag\": \"pending_review\",\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://flows.super.ai/api/task-tags")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"tags\": [\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"add\",\n \"tag\": \"reviewed\",\n \"tag_metadata\": {\n \"reviewer\": \"user@example.com\"\n },\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n },\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"remove\",\n \"tag\": \"pending_review\",\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://flows.super.ai/api/task-tags")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tags\": [\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"add\",\n \"tag\": \"reviewed\",\n \"tag_metadata\": {\n \"reviewer\": \"user@example.com\"\n },\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n },\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"remove\",\n \"tag\": \"pending_review\",\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"tags": [
{
"status": "added"
},
{
"status": "removed"
},
{
"status": "already_exists"
}
]
}task-tags
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)
PATCH
/
api
/
task-tags
Add or remove task tags in batch
curl --request PATCH \
--url https://flows.super.ai/api/task-tags \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tags": [
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "add",
"tag": "reviewed",
"tag_metadata": {
"reviewer": "user@example.com"
},
"tag_type": "review_status",
"task_name": "extract_data"
},
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "remove",
"tag": "pending_review",
"tag_type": "review_status",
"task_name": "extract_data"
}
]
}
'import requests
url = "https://flows.super.ai/api/task-tags"
payload = { "tags": [
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "add",
"tag": "reviewed",
"tag_metadata": { "reviewer": "user@example.com" },
"tag_type": "review_status",
"task_name": "extract_data"
},
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "remove",
"tag": "pending_review",
"tag_type": "review_status",
"task_name": "extract_data"
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
tags: [
{
flow_execution_id: '123e4567-e89b-12d3-a456-426614174000',
operation: 'add',
tag: 'reviewed',
tag_metadata: {reviewer: 'user@example.com'},
tag_type: 'review_status',
task_name: 'extract_data'
},
{
flow_execution_id: '123e4567-e89b-12d3-a456-426614174000',
operation: 'remove',
tag: 'pending_review',
tag_type: 'review_status',
task_name: 'extract_data'
}
]
})
};
fetch('https://flows.super.ai/api/task-tags', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://flows.super.ai/api/task-tags",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'tags' => [
[
'flow_execution_id' => '123e4567-e89b-12d3-a456-426614174000',
'operation' => 'add',
'tag' => 'reviewed',
'tag_metadata' => [
'reviewer' => 'user@example.com'
],
'tag_type' => 'review_status',
'task_name' => 'extract_data'
],
[
'flow_execution_id' => '123e4567-e89b-12d3-a456-426614174000',
'operation' => 'remove',
'tag' => 'pending_review',
'tag_type' => 'review_status',
'task_name' => 'extract_data'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://flows.super.ai/api/task-tags"
payload := strings.NewReader("{\n \"tags\": [\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"add\",\n \"tag\": \"reviewed\",\n \"tag_metadata\": {\n \"reviewer\": \"user@example.com\"\n },\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n },\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"remove\",\n \"tag\": \"pending_review\",\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://flows.super.ai/api/task-tags")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"tags\": [\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"add\",\n \"tag\": \"reviewed\",\n \"tag_metadata\": {\n \"reviewer\": \"user@example.com\"\n },\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n },\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"remove\",\n \"tag\": \"pending_review\",\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://flows.super.ai/api/task-tags")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tags\": [\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"add\",\n \"tag\": \"reviewed\",\n \"tag_metadata\": {\n \"reviewer\": \"user@example.com\"\n },\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n },\n {\n \"flow_execution_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"operation\": \"remove\",\n \"tag\": \"pending_review\",\n \"tag_type\": \"review_status\",\n \"task_name\": \"extract_data\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"tags": [
{
"status": "added"
},
{
"status": "removed"
},
{
"status": "already_exists"
}
]
}Authorizations
BearerAuthAPIKeyAuth
JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN
Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Body
application/json
Batch request to add or remove multiple task execution tags.
Supports mixed operations (add and remove) in a single atomic transaction. All operations succeed together or all fail. Efficient for bulk tagging.
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 tasks
- Remove tags from multiple tasks
- Add and remove different tags in same request
Practical limit: 1-100 operations per request for performance. For bulk tagging beyond 100 operations, split into multiple requests.
Required array length:
1 - 100 elementsShow child attributes
Show child attributes
Example:
[
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "add",
"tag": "reviewed",
"tag_metadata": { "reviewer": "user@example.com" },
"tag_type": "review_status",
"task_name": "extract_data"
},
{
"flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
"operation": "remove",
"tag": "pending_review",
"tag_type": "review_status",
"task_name": "extract_data"
}
]
Response
Task tags successfully updated
Response from batch tag operations.
Returns status for each operation in request array order. Array length matches request array length (1:1 correspondence).
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, status3]
All operations complete (no partial failures). Check each status to determine individual operation outcomes. Use array index to match operations with results.
Show child attributes
Show child attributes
Example:
[
{ "status": "added" },
{ "status": "removed" },
{ "status": "already_exists" }
]