Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Manage tags

All tag operations use the Tagging API. Authentication requires an account API token or user API token with appropriate permissions.

Set tags on a resource

Use PUT to set tags on an account-level resource. This operation replaces all existing tags on the resource.

Terminal window
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "worker",
    "resource_id": "'"$RESOURCE_ID"'",
    "tags": {
      "environment": "production",
      "team": "platform",
      "cost-center": "engineering"
    }
  }'

For zone-level resources, use the zone endpoint:

Terminal window
curl -X PUT "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/tags" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "zone",
    "resource_id": "'"$ZONE_ID"'",
    "tags": {
      "environment": "production",
      "customer": "acme-corp"
    }
  }'

Some resource types require additional fields. Refer to supported resource types for details.

Get tags for a resource

Retrieve tags for a specific resource:

Terminal window
curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags?resource_type=worker&resource_id=$RESOURCE_ID" \
  -H "Authorization: Bearer $API_TOKEN"

Add a single tag

The API does not support partial updates — PUT always replaces all tags. To add a tag without removing existing ones, use the GET, merge, PUT pattern:

  1. GET the current tags.
Terminal window
curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags?resource_type=worker&resource_id=$RESOURCE_ID" \
  -H "Authorization: Bearer $API_TOKEN"


# Response: {"result": {"tags": {"environment": "production", "team": "platform"}}}
  1. Merge the new tag into the existing set locally.
{
  "environment": "production",
  "team": "platform",
  "cost-center": "engineering"
}
  1. PUT the complete merged tag set.
Terminal window
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "worker",
    "resource_id": "'"$RESOURCE_ID"'",
    "tags": {
      "environment": "production",
      "team": "platform",
      "cost-center": "engineering"
    }
  }'

Remove a single tag

Follow the same GET, merge, PUT pattern, but omit the tag you want to remove from the set before calling PUT.

Delete all tags

To remove all tags from a resource:

Terminal window
curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "worker",
    "resource_id": "'"$RESOURCE_ID"'"
  }'

This returns 204 No Content on success. Only use DELETE when you want to remove all tags from a resource (for example, when decommissioning it).