Tags

Tags let you organize and filter agents. There are two types of tags:

User tags — Created and managed by users with custom colors
System tags — Created by Firetiger (prefixed with firetiger:), always displayed in grey, read-only

Service: firetiger.tags.v1.TagsService

Resource name pattern: tags/{tag_id}

Access: Read-write (user tags only; system tags are read-only)

Resource type: Tag

Example flow

Create a tag, assign it to an agent, then list tags.

1. Create a tag

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/CreateTag" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "production",
    "tag": {
      "display_name": "Production",
      "description": "Agents monitoring production systems",
      "color": "#5E6AD2"
    }
  }'

{
  "tag": {
    "name": "tags/production",
    "displayName": "Production",
    "description": "Agents monitoring production systems",
    "color": "#5E6AD2",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

2. Assign tag to an agent

curl -X POST "https://api.cloud.firetiger.com/firetiger.nxagent.v2.AgentService/UpdateAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "agents/my-agent",
      "tags": ["tags/production"]
    },
    "update_mask": "tags"
  }'

3. List all tags

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/ListTags" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "tags": [
    {
      "name": "tags/production",
      "displayName": "Production",
      "description": "Agents monitoring production systems",
      "color": "#5E6AD2",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ]
}

Methods

Method	Description
CreateTag	Create a new tag
GetTag	Retrieve a tag by name
UpdateTag	Update an existing tag
DeleteTag	Soft-delete a tag
ListTags	List tags with filtering and pagination

CreateTag

Create a new user tag. Cannot create system tags (those with firetiger: prefix).

POST /firetiger.tags.v1.TagsService/CreateTag

Request body

Field	Type	Required	Description
`tag_id`	string	Yes	ID for the new tag (alphanumeric, hyphens, underscores, colons)
`tag`	Tag	Yes	The tag to create

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/CreateTag" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "deploy-monitoring",
    "tag": {
      "display_name": "Deployment Monitoring",
      "color": "#10B981"
    }
  }'

Response

{
  "tag": {
    "name": "tags/deploy-monitoring",
    "displayName": "Deployment Monitoring",
    "color": "#10B981",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

GetTag

Retrieve a tag by name.

POST /firetiger.tags.v1.TagsService/GetTag

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the tag

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/GetTag" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "tags/production"}'

UpdateTag

Update an existing tag. Use update_mask to specify which fields to modify. Cannot update system tags.

POST /firetiger.tags.v1.TagsService/UpdateTag

Request body

Field	Type	Required	Description
`tag`	Tag	Yes	The tag with `name` set and updated fields
`update_mask`	string	No	Comma-separated list of fields to update. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/UpdateTag" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "tags/production",
      "color": "#EF4444"
    },
    "update_mask": "color"
  }'

DeleteTag

Soft-delete a tag. The resource will still be accessible via Get but excluded from List results unless show_deleted is set. Cannot delete system tags.

POST /firetiger.tags.v1.TagsService/DeleteTag

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the tag to delete

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/DeleteTag" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "tags/production"}'

List tags with optional filtering and pagination.

POST /firetiger.tags.v1.TagsService/ListTags

Request body

Field	Type	Required	Description
`filter`	string	No	Filter expression (e.g., `system = true`)
`order_by`	string	No	Field to sort by (e.g., `create_time desc`)
`page_size`	integer	No	Maximum results per page
`page_token`	string	No	Token for the next page of results
`show_deleted`	boolean	No	Include soft-deleted tags

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.tags.v1.TagsService/ListTags" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"filter": "system = false", "page_size": 25}'

Response

{
  "tags": [
    {
      "name": "tags/production",
      "displayName": "Production",
      "color": "#5E6AD2",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}