Skip to content

Assign and unassign tags

POST/tags/assignment

Endpoint API · Endpoint Tags

Assign and unassign tags to endpoints.

Required permissionendpoint-computer-tag-management:write OR endpoint-server-tag-management:write

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.

Request body

Content type: application/json

Request body fields

assignarray of object
List of tags to assign.
Must contain 0–15 items. Items must be unique.
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
unassignarray of object
List of tags to unassign.
Must contain 0–1000 items. Items must be unique.
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
unassignAllboolean
Set to true to unassign all tags.
Must be one of: true.
entityIdsarray of string (uuid)required
List of entityIds to be assigned to and unassigned from.
Must contain 1–1000 items. Items must be unique.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/endpoint/v1/tags/assignment" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"entityIds\": [
    \"17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11\",
    \"28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12\",
    \"38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13\"
  ],
  \"unassign\": [
    {
      \"key\": \"Country\",
      \"value\": \"USA\"
    },
    {
      \"key\": \"Department\",
      \"value\": \"Finance\"
    }
  ],
  \"assign\": [
    {
      \"key\": \"Project\",
      \"value\": \"Apollo\"
    },
    {
      \"key\": \"Department\",
      \"value\": \"HR\"
    },
    {
      \"key\": \"Country\",
      \"value\": \"UK\"
    },
    {
      \"key\": \"Region\",
      \"value\": \"\"
    }
  ]
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/tags/assignment",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'entityIds': [   '17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11',
                     '28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12',
                     '38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13'],
    'unassign': [   {'key': 'Country', 'value': 'USA'},
                    {'key': 'Department', 'value': 'Finance'}],
    'assign': [   {'key': 'Project', 'value': 'Apollo'},
                  {'key': 'Department', 'value': 'HR'},
                  {'key': 'Country', 'value': 'UK'},
                  {'key': 'Region', 'value': ''}]},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "entityIds": [
    "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11",
    "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12",
    "38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13"
  ],
  "unassign": [
    {
      "key": "Country",
      "value": "USA"
    },
    {
      "key": "Department",
      "value": "Finance"
    }
  ],
  "assign": [
    {
      "key": "Project",
      "value": "Apollo"
    },
    {
      "key": "Department",
      "value": "HR"
    },
    {
      "key": "Country",
      "value": "UK"
    },
    {
      "key": "Region",
      "value": ""
    }
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/tags/assignment" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/endpoint/v1/tags/assignment", strings.NewReader(`{
  "entityIds": [
    "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11",
    "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12",
    "38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13"
  ],
  "unassign": [
    {
      "key": "Country",
      "value": "USA"
    },
    {
      "key": "Department",
      "value": "Finance"
    }
  ],
  "assign": [
    {
      "key": "Project",
      "value": "Apollo"
    },
    {
      "key": "Department",
      "value": "HR"
    },
    {
      "key": "Country",
      "value": "UK"
    },
    {
      "key": "Region",
      "value": ""
    }
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/tags/assignment", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "entityIds": [
    "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11",
    "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12",
    "38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13"
  ],
  "unassign": [
    {
      "key": "Country",
      "value": "USA"
    },
    {
      "key": "Department",
      "value": "Finance"
    }
  ],
  "assign": [
    {
      "key": "Project",
      "value": "Apollo"
    },
    {
      "key": "Department",
      "value": "HR"
    },
    {
      "key": "Country",
      "value": "UK"
    },
    {
      "key": "Region",
      "value": ""
    }
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

200 — Success.

Response fields

itemsarray of string (uuid)
Array of entity IDs that were successfully processed with no failures. Only present when there are successful entities.
Must contain at least 1 item.
errorsarray of object
Detailed error information for entities that had failures. Only present when there are errors.
Must contain at least 1 item.
Error information for an entity that had failures during tag assignment operations.
Show child attributesHide child attributes
entityIdstring (uuid)required
The entity ID that had failures.
statusstringrequired
Status of operations for this entity. failed indicates all operations failed for this entity. partial indicates some operations succeeded, some failed.
Must be one of: failed, partial.
assignedarray of object
Tags that were successfully assigned to this entity.
Must contain at least 1 item.
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
unassignedarray of object
Tags that were successfully unassigned from this entity.
Must contain at least 1 item.
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
tagErrorsarray of object
Per-tag operation failures for this entity. Note: The server implementation will cap this array at 100 entries per entity. If an entity has more than 100 tag errors, only the first 100 will be included in the response. Errors are ordered by priority (most critical first): ENTITY_NOT_FOUND, WOULD_EXCEED_MAX_TAGS, TAG_KEY_CONFLICT, TAG_OWNED_BY_THIRD_PARTY, TAG_ALREADY_IN_STATE. This ensures the most important errors are included when the array is truncated.
Must contain 1–100 items.
Error information for a specific tag operation that failed.
Show child attributesHide child attributes
tagobjectrequired
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
operationstringrequired
The operation that failed.
Must be one of: assign, unassign.
codestringrequired
Error code indicating the type of failure. When multiple errors occur for an entity, they are ordered by priority (most critical first): 1. ENTITY_NOT_FOUND - The entity does not exist (highest priority; if present, no further operations are attempted for this entity). 2. WOULD_EXCEED_MAX_TAGS - Assignment would exceed the maximum number of tags allowed on an endpoint. 3. TAG_KEY_CONFLICT - Tag key already exists with a different value on the endpoint. 4. TAG_OWNED_BY_THIRD_PARTY - Tag cannot be unassigned because it was not created by Sophos and is managed externally. 5. TAG_ALREADY_IN_STATE - Tag is already in the desired state (already assigned with same value when assigning, or already unassigned when unassigning).
Must be one of: ENTITY_NOT_FOUND, WOULD_EXCEED_MAX_TAGS, TAG_KEY_CONFLICT, TAG_OWNED_BY_THIRD_PARTY, TAG_ALREADY_IN_STATE.
messagestring
Human-readable error message describing the failure.

Errors

Status Meaning
400 Invalid request.
401 Authentication required.
403 Authorization required.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff11",
    "28dd896f-ee9f-4f7d-a2a2-6a8c0b48ff12"
  ],
  "errors": [
    {
      "entityId": "38dd896f-ee9f-4f7d-a2a2-6a8c0b48ff13",
      "status": "partial",
      "assigned": [
        {
          "key": "Project",
          "value": "Apollo"
        }
      ],
      "unassigned": [
        {
          "key": "Department",
          "value": "Finance"
        }
      ],
      "tagErrors": [
        {
          "tag": {
            "key": "Country",
            "value": "UK"
          },
          "operation": "assign",
          "code": "TAG_KEY_CONFLICT",
          "message": "Tag key 'Country' already exists with value 'USA'"
        }
      ]
    }
  ]
}

See the guide for a narrative walkthrough of this API.