Product UpdatesStatus PageWorkato Academy
English
日本語
Start for free
Developer API
Endpoints

Developer API - Tag assignments ​

Use this endpoint to apply tags to or remove tags from assets in your workspace.

TAG APIS

To create, retrieve, update, and delete tags programmatically, refer to our Environment management API documentation.

Rate limits ​

Tag assignment resources have the following rate limits:

TypeResourceQuota
AllAll Tag assignments endpoints60 requests per minute

Quick reference ​

TypeResourceDescription
POST/api/tags_assignmentsApply tags to or remove tags from assets in your workspace.

Manage tag assignments ​

Applies or removes tags from assets in your workspace. This endpoint can tag recipes and connections only. You can assign one or more tags to these assets or remove existing tags.

POST https://YOUR_DATA_CENTER/api/tags_assignments

Payload ​

NameTypeDescription
add_tagsarray of strings
optional		An array of tag handles to be added, for example tag-Abx8kQ2e-Tn4WzR-CD. Use the tag handle, not the tag title. Each handle represents an existing tag to be applied to the specified assets.
remove_tagsarray of strings
optional		An array of tag handles to be removed. Each handle represents a tag to be removed from the specified assets.
recipe_idsarray of integers
conditional		An array of recipe IDs to tag or untag. Required if connection_ids is not provided.
connection_idsarray of integers
conditional		An array of connection IDs to tag or untag. Required if recipe_ids is not provided.

USE TAG HANDLES, NOT TAG TITLES

This endpoint accepts tag handles only, and a tag must exist before you can assign it. Retrieve the handle of an existing tag with the List tags (GET /api/tags) endpoint or Create a tag (POST /api/tags), which returns the tag handle.

The request returns 200 OK and doesn't apply a tag when a value in add_tags or remove_tags doesn't match an existing tag handle. The response doesn't include an error. A request with both valid and unrecognized values applies the valid handles and ignores invalid input.

A tag is available in all environments of your workspace. Tag assignments apply only to the recipes and connections in the environment associated with your API client.

Refer to Create and assign a tag for a complete example that creates a tag, assigns it to a recipe, and verifies the result.

Sample request ​

This request adds a tag to a connection and a recipe in Workato.

shell
curl  -X POST "https://YOUR_DATA_CENTER/api/tags_assignments" \
      -H "Authorization: Bearer <api_token>" \
      -H "Content-Type: application/json" \
      -d '{
            "add_tags": [":add_tag_1"],
            "recipe_ids": [:recipe_id_1],
            "connection_ids": [:connection_id_1]
          }'

Response ​

A 200 OK status means Workato accepted the request. No content is returned in the response body.

The endpoint also returns 200 OK when a tag handle isn't recognized, so a 200 OK status doesn't confirm that the tag was applied. Refer to Create and assign a tag for an example of retrieving the tags assigned to an asset.

Create and assign a tag ​

This example creates a tag, assigns it to a recipe, and confirms the assignment. Use connection_ids in place of recipe_ids to tag a connection.

1

Create the tag with the POST /api/tags endpoint. The title field is the only required field.

shell
curl  -X POST "https://YOUR_DATA_CENTER/api/tags" \
      -H "Authorization: Bearer <api_token>" \
      -H "Content-Type: application/json" \
      -d '{
            "title": "HR"
          }'

Copy the handle value from the response. The handle in this example is tag-Abx8sFmg-NWx3Lb-CD. The description is null because the request doesn't set one, and Workato assigns a random color.

json
{
  "data": {
    "handle": "tag-Abx8sFmg-NWx3Lb-CD",
    "title": "HR",
    "description": null,
    "color": "plum"
  }
}
2

Assign the tag to the recipe by passing the handle from the previous step in add_tags, not the title HR.

shell
curl  -X POST "https://YOUR_DATA_CENTER/api/tags_assignments" \
      -H "Authorization: Bearer <api_token>" \
      -H "Content-Type: application/json" \
      -d '{
            "add_tags": ["tag-Abx8sFmg-NWx3Lb-CD"],
            "recipe_ids": [1234567]
          }'
3

Verify the assignment by listing the tags assigned to the recipe with the q[recipe_id_eq] query parameter of the List tags endpoint. The response includes the tag if the assignment succeeded.

shell
curl  -X GET "https://YOUR_DATA_CENTER/api/tags?q[recipe_id_eq]=1234567" \
      -H "Authorization: Bearer <api_token>"
json
{
  "data": {
    "tags": [
      {
        "handle": "tag-Abx8sFmg-NWx3Lb-CD",
        "title": "HR",
        "description": null,
        "color": "plum",
        "created_at": "2026-10-14T09:11:17.344-07:00",
        "updated_at": "2026-10-14T09:11:17.344-07:00"
      }
    ]
  }
}

An empty tags array means the tag wasn't applied. Check that add_tags contains the tag handle and not the title.

Last updated: