Tags

Tags can be used to add metadata, or keywords, to intelligence data and Workflow Cases. They provide a way to quickly identify or follow associated activities of a particular interest across ThreatConnect.

Endpoint: /api/v3/tags

Available Fields

You can retrieve a list of available fields for the /v3/tags endpoint, including each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/tags

Hint

To view all fields, including read-only fields, include the ?show=readonly query parameter.

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request for the tags object.

Field Description Type Required for Creation? Updatable?
description The Tag’s description String FALSE TRUE
name The Tag’s name String TRUE TRUE
owner The Organization, Community, or Source to which the Tag belongs String FALSE FALSE

Create Tags

The basic format for creating a Tag is:

POST /v3/tags
{
    "name": "Tag name goes here",
    "description": "Tag description goes here"
}

For example, the following query will create a Phishing Tag:

POST /v3/tags
{
    "name": "Phishing",
    "description": "Apply this Tag to objects related to phishing attacks."
}

JSON Response

{
    "data": {
        "id": 1,
        "name": "Phishing",
        "owner": "Demo Organization",
        "description": "Apply this Tag to objects related to phishing attacks.",
        "lastUsed": "2021-11-08T18:01:36Z"
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a POST request for the tags object.

Retrieve Tags

Retrieve All Tags

To retrieve all Tags, use the following query:

GET /v3/tags

JSON Response

{
    "data": [
        {
            "id": 1,
            "name": "Phishing",
            "owner": "Demo Organization",
            "description": "Apply this Tag to objects related to phishing attacks.",
            "lastUsed": "2021-11-08T18:01:36Z"
        },
        {
            "id": 2,
            "name": "Malicious Host",
            "owner": "Demo Organization",
            "lastUsed": "2021-11-14T13:54:20Z"
        },
        {
            "id": 3,
            "name": "Robbery",
            "owner": "Demo Organization",
            "lastUsed": "2021-11-14T18:52:38Z"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Tag

To retrieve a specific Tag, use a query in the following format:

GET /v3/tags/{tagId}

For example, the following query will return information about the Tag with ID 2:

GET /v3/tags/2

JSON Response

{
    "data": {
        "id": 2,
        "name": "Malicious Host",
        "owner": "Demo Organization",
        "lastUsed": "2021-11-14T13:54:20Z"
    },
    "status": "Success"
}

Request Additional Fields

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Tags

The basic format for updating a Tag is:

PUT /v3/tags/{tagId}
{
    {updatedField}: {updatedValue}
}

For example, the following query will rename the Tag with ID 1 to Phishing Attack:

PUT /v3/tags/1
{
    "name": "Phishing Attack"
}

JSON Response

{
    "data": {
        "id": 1,
        "name": "Phishing Attack",
        "owner": "Demo Organization",
        "description": "Apply this Tag to objects related to phishing attacks.",
        "lastUsed": "2021-11-08T18:01:36Z"
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a PUT request for the tags object.

Delete Tags

The basic format to delete a Tag is:

DELETE /v3/tags/{tagId}

For example, the following query will delete the Tag with ID 1:

DELETE /v3/tags/1

JSON Response

{
    "message": "Deleted",
    "status": "Success"
}

Attention

Deleted Tags will be automatically removed from any objects to which they are applied.