Create Tags

Tool Name: airdroid_business_tag_batch_create

Risk Level: 🟡 Write (medium-risk write: creates org-visible tags)

Execution Mode: ⚡ Synchronous

Category: Device Management (Tags)

Quick Start (Copy & Use)

Summary: Create one or more organization device tags and return each new tag’s ID and final name.

Prerequisites: TagNames (1–100 distinct strings, 1–30 characters after trim).

Success Criteria: StatusCode == 200 and ErrorMessage is empty and Tags length matches the number of names you submitted. Do not treat StatusCode == 200 alone as success—always check ErrorMessage.

What to Do Next: Pass returned tag_id values to Set Tags or store them for later device assignment.

Minimal Request Example:

{
  "TagNames": [
    "Chicago Warehouse",
    "Priority Devices"
  ]
}

Minimal Response Example:

{
  "Tags": [
    { "tag_id": 4102, "name": "Chicago Warehouse" },
    { "tag_id": 4103, "name": "Priority Devices" }
  ],
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Create a Single Tag

When to use: One new label for later device assignment.

{
  "TagNames": ["Chicago Warehouse"]
}

Recipe 2: Create Several Tags in One Call

When to use: Bootstrap a small tag set (stay within 100 names per call).

{
  "TagNames": ["Sales", "VIP", "Loaner Pool"]
}

Recipe 3: Name Already Exists (Do Not Recreate)

When to use: You are unsure whether the tag exists.

1. Prefer Batch Resolve Tag IDs by Name first to get existing IDs.
2. Call Create Tags only for names that are still missing.
3. If Create Tags returns StatusCode 200 with a non-empty ErrorMessage and the Hint about existing names, use Batch Resolve Tag IDs by Name—do not retry the same names. The exact ErrorMessage text comes from the upstream service and is not fixed.

1. Overview

1.1 Description

Creates organization-level device tags. On success, returns tag_id and final saved name for every requested name that was created.

1.2 When to Use

• Add new classification tags before assigning them to devices
• Prepare tag IDs for Set Tags workflows
• Bulk-create a predefined tag vocabulary

1.3 Execution Mode and Response

Synchronous. Tags are created immediately; results appear in Tags when ErrorMessage is empty.

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`TagNames`

• Type: string-array (JSON array of strings)
• Rules:
  • 1–100 names per call
  • Each name: 1–30 characters after leading/trailing spaces are removed
  • No control characters (for example newline \n, tab \t, or other ASCII control codes)
  • No duplicates after trimming
• Duplicate in organization: If any name already exists, the call fails (ErrorMessage non-empty, Tags empty). Use Batch Resolve Tag IDs by Name for existing tags.
• Fill in a GI workflow node:
  • Constants: Enter a JSON string array in the node input, for example ["Chicago Warehouse", "Priority Devices"].
  • Reference upstream output: Map a prior node field into the array when your workflow supplies dynamic names, for example ["{{upstream.new_tag_name}}"] or a merged list built in an earlier step—keep each item a string and respect the 1–100 / 1–30 character rules.
• Example:

  ["Chicago Warehouse", "Priority Devices"]
  

2.3 Parameter Combination Logic

• Only TagNames is required; one request either creates every name or fails as a whole—there is no partial success.

3. Outputs

3.1 Response Examples

Success:

{
  "Tags": [
    { "tag_id": 4102, "name": "Chicago Warehouse" }
  ],
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Business failure (duplicate name):

When the upstream business code indicates a duplicate name, StatusCode stays 200, Tags is [], and Hint (not a fixed ErrorMessage string) tells you to resolve existing IDs. **ErrorMessage is copied from the upstream msg field and may vary by locale or wording—use Hint and empty Tags to detect this case; do not match ErrorMessage text literally.

{
  "Tags": [],
  "Hint": "One or more tag names already exist; use 'Batch Resolve Tag IDs by Name' to obtain existing tag IDs instead of creating duplicates.",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": "<upstream message; not a fixed tool string>"
}

Validation failure:

{
  "Tags": [],
  "Hint": "Provide 1-100 distinct tag names, then retry.",
  "Retryable": false,
  "OriginalStatusCode": 0,
  "StatusCode": -1,
  "ErrorMessage": "TagNames must contain 1-100 names."
}

3.2 Field Descriptions

3.3 Status Values in `Tags`

Each successful item includes the final saved name (after trim) and tag_id as a positive integer (not boolean, not zero).

4. Examples

4.1 Create Two Tags

Request:

{ "TagNames": ["Chicago Warehouse", "Priority Devices"] }

Response: See Quick Start minimal response.

4.2 Duplicate Name After Trim

Request:

{ "TagNames": ["  Sales  ", "Sales"] }

Response: StatusCode -1, ErrorMessage about duplicate after trimming.

4.3 Existing Organization Name

Request:

{ "TagNames": ["Existing Label"] }

Response: StatusCode 200, non-empty ErrorMessage, empty Tags, Hint points to Batch Resolve Tag IDs by Name.

5. Error Handling

5.1 StatusCode Semantics (This Action)

HTTP mapping (tool output uses StatusCode 500, not 403/401 on the tool layer):

5.2 Common Errors

5.3 Agent Self-Healing

6. Best Practices

6.1 Performance

• Create up to 100 tags per call; batch new names instead of one call per tag when safe.

6.2 Security

• 🟡 Write operation: new tags are visible org-wide; avoid generic names that collide with existing labels.

6.3 Idempotency

• Not idempotent for duplicate names (call fails rather than returning existing IDs).
• A successful create followed by the same names again hits business failure—it does not return the existing IDs.
• Re-running with the same new names after success may fail if names now exist.

7. Related Tools

8. Tool Chains

8.1 Create Then Assign

Create Tags → Set Tags (use tag_id from Tags[])

8.2 Resolve-or-Create Pattern

Batch Resolve Tag IDs by Name → Create Tags (only missing names) → Set Tags

Appendix Reference:

• Field Reference
• Error Codes