← Resource Tagging / resource-tagging / how-to

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.

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:

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:

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:

GET the current tags.

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"}}}

Merge the new tag into the existing set locally.

{
  "environment": "production",
  "team": "platform",
  "cost-center": "engineering"
}

PUT the complete merged tag set.

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:

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