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' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "tags": [
    {
      "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "tag": "<string>",
      "tag_type": "<string>",
      "task_name": "<string>",
      "tag_metadata": {
        "notes": "Looks good",
        "reviewer": "user@example.com"
      }
    }
  ]
}
'

import requests

url = "https://flows.super.ai/api/task-tags"

payload = { "tags": [
        {
            "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "tag": "<string>",
            "tag_type": "<string>",
            "task_name": "<string>",
            "tag_metadata": {
                "notes": "Looks good",
                "reviewer": "user@example.com"
            }
        }
    ] }
headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'X-API-Key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tags: [
      {
        flow_execution_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        tag: '<string>',
        tag_type: '<string>',
        task_name: '<string>',
        tag_metadata: {notes: 'Looks good', reviewer: 'user@example.com'}
      }
    ]
  })
};

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' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'tag' => '<string>',
                'tag_type' => '<string>',
                'task_name' => '<string>',
                'tag_metadata' => [
                                'notes' => 'Looks good',
                                'reviewer' => 'user@example.com'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"tag\": \"<string>\",\n      \"tag_type\": \"<string>\",\n      \"task_name\": \"<string>\",\n      \"tag_metadata\": {\n        \"notes\": \"Looks good\",\n        \"reviewer\": \"user@example.com\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	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("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tags\": [\n    {\n      \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"tag\": \"<string>\",\n      \"tag_type\": \"<string>\",\n      \"task_name\": \"<string>\",\n      \"tag_metadata\": {\n        \"notes\": \"Looks good\",\n        \"reviewer\": \"user@example.com\"\n      }\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["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tags\": [\n    {\n      \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"tag\": \"<string>\",\n      \"tag_type\": \"<string>\",\n      \"task_name\": \"<string>\",\n      \"tag_metadata\": {\n        \"notes\": \"Looks good\",\n        \"reviewer\": \"user@example.com\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "tags": [
    {}
  ]
}

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' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "tags": [
    {
      "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "tag": "<string>",
      "tag_type": "<string>",
      "task_name": "<string>",
      "tag_metadata": {
        "notes": "Looks good",
        "reviewer": "user@example.com"
      }
    }
  ]
}
'

import requests

url = "https://flows.super.ai/api/task-tags"

payload = { "tags": [
        {
            "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "tag": "<string>",
            "tag_type": "<string>",
            "task_name": "<string>",
            "tag_metadata": {
                "notes": "Looks good",
                "reviewer": "user@example.com"
            }
        }
    ] }
headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'X-API-Key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tags: [
      {
        flow_execution_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        tag: '<string>',
        tag_type: '<string>',
        task_name: '<string>',
        tag_metadata: {notes: 'Looks good', reviewer: 'user@example.com'}
      }
    ]
  })
};

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' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'tag' => '<string>',
                'tag_type' => '<string>',
                'task_name' => '<string>',
                'tag_metadata' => [
                                'notes' => 'Looks good',
                                'reviewer' => 'user@example.com'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"tag\": \"<string>\",\n      \"tag_type\": \"<string>\",\n      \"task_name\": \"<string>\",\n      \"tag_metadata\": {\n        \"notes\": \"Looks good\",\n        \"reviewer\": \"user@example.com\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	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("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tags\": [\n    {\n      \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"tag\": \"<string>\",\n      \"tag_type\": \"<string>\",\n      \"task_name\": \"<string>\",\n      \"tag_metadata\": {\n        \"notes\": \"Looks good\",\n        \"reviewer\": \"user@example.com\"\n      }\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["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tags\": [\n    {\n      \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"tag\": \"<string>\",\n      \"tag_type\": \"<string>\",\n      \"task_name\": \"<string>\",\n      \"tag_metadata\": {\n        \"notes\": \"Looks good\",\n        \"reviewer\": \"user@example.com\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "tags": [
    {}
  ]
}

Authorizations

X-API-Key

string

header

required

API key authentication. Include your API key in the X-API-Key header as: X-API-Key YOUR_API_KEY

Example:

X-API-Key: saf_1234567890

Authorization

string

header

required

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.

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).