# Device Tag APIs

Tags are labels added to devices to group them together. Tags are useful when searching devices using device filters. Tags are also useful when OTA updates (deployments) need to be deployed on a subset of devices.

Tagging a device is a two-step process.

  • Create a tag.
  • Attach the tag to a device.

A tag can be attached to multiple devices and multiple tags can be attached to a single device.

# 1. Create a tag

curl https://api.socketxp.com/v1/tag/:tag_name \
  -X POST \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Usage

curl https://api.socketxp.com/v1/tag/"light-sensor" \
  -X POST \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK

{"TagId": "1234-abc-12345-a1b2c3d4-123"}

# 2. Get all tags

curl https://api.socketxp.com/v1/tag \
  -X GET \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Usage

curl https://api.socketxp.com/v1/tag \
  -X GET \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK

[
    {
        "TagId": "1234-abc-12345-a1b2c3d4-123",
        "TagName": "light-sensor"
    },
    {
        "TagId": "5678-efg-56789-a1b2c3d4-567",
        "TagName": "customer-site-1"
    },
    {
        "TagId": "7777-jkl-8888-a1b2c3d4-999",
        "TagName": "RaspberryPi"
    }
]

# 3. Delete a tag

curl https://api.socketxp.com/v1/tag/:tag_id \
  -X DELETE \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Usage

curl https://api.socketxp.com/v1/tag/"1234-abc-12345-a1b2c3d4-123" \
  -X DELETE \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK

# 4. Add a tag to a device

Use the below API to add a tag to a device. You need to create the tag first before you could add it to the device.

curl https://api.socketxp.com/v1/devices/:device_id/tag/:tag_id \
  -X POST \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Usage

curl https://api.socketxp.com/v1/devices/"2222-jkl-3333-a1b2c3d4-444"/tag/"1234-abc-12345-a1b2c3d4-123" \
  -X POST \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK

# 5. Delete a tag from a device

curl https://api.socketxp.com/v1/devices/:device_id/tag/:tag_id \
  -X DELETE \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Usage

curl https://api.socketxp.com/v1/devices/"2222-jkl-3333-a1b2c3d4-444"/tag/"1234-abc-12345-a1b2c3d4-123" \
  -X DELETE \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK