Indicator Attributes

Attributes are key/value data sets that can be added to any Indicator. This type of metadata provides an excellent way to organize, categorize, and integrate Indicators into an organization’s analytic workflow.

Endpoint: /api/v3/indicatorAttributes

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/indicatorAttributes endpoint:

OPTIONS /v3/indicatorAttributes

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

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 to the /v3/indicatorAttributes endpoint.

Field

Description

Type

Required for Creation?

Updatable?

default

Indicates whether the Attribute is the default Attribute of its type for the Indicator to which it is added (this field applies to certain Attribute and data types only)

Boolean

FALSE

TRUE

indicatorId

The ID of the Indicator to which the Attribute is added

Integer

TRUE

FALSE

pinned

Indicates whether the Attribute is to be displayed as a Pinned Attribute on the Details screen for the Indicator to which the Attribute is added

Boolean

FALSE

TRUE

securityLabels

A list of Security Labels applied to the Attribute

Security Label Object

FALSE

TRUE

source

The Attribute’s source

String

FALSE

TRUE

type [1]

The Attribute’s type

String

TRUE

FALSE

value

The Attribute’s value

String

TRUE

TRUE

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/indicatorAttributes endpoint:

OPTIONS /v3/indicatorAttributes/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/indicatorAttributes endpoint:

OPTIONS /v3/indicatorAttributes/tql

Create Indicator Attributes

The following example illustrates the basic format for creating an Indicator Attribute:

POST /v3/indicatorAttributes
Content-Type: application/json

{
    "indicatorId": 12345,
    "type": "Attribute type goes here",
    "value": "Attribute value goes here"
}

For example, the following request will create an Attribute and add it to the Indicator whose ID is 20:

POST /v3/indicatorAttributes
Content-Type: application/json

{
    "indicatorId": 20,
    "source": "Phase of Intrusion",
    "type": "Additional Analysis and Context",
    "value": "Host used by hacker conglomerate traced to Iran."
}

JSON Response

{
    "data": {
        "id": 10,
        "dateAdded": "2021-11-09T13:32:37Z",
        "type": "Additional Analysis and Context",
        "value": " Host used by hacker conglomerate traced to Iran.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T13:32:37Z",
        "pinned": false,
        "default": false
    },
    "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 to the /v3/indicatorAttributes endpoint.

Hint

Indicator Attributes can also be created and added to an Indicator when creating the Indicator. See the “Create Indicators” section of Indicators for more information.

Retrieve Indicator Attributes

The following section describes how to retrieve Indicator Attributes via the /v3/indicatorAttributes endpoint. In addition to the methods described in this section, you can send the following request to retrieve Attributes added to a specific Indicator: GET /v3/indicators/{indicatorId or indicatorSummary}?fields=attributes.

Retrieve All Indicator Attributes

Send the following request to retrieve data for all Indicator Attributes:

GET /v3/indicatorAttributes

JSON Response

{
    "data": [
        {
            "id": 10,
            "dateAdded": "2021-11-09T13:32:37Z",
            "type": "Additional Analysis and Context",
            "value": "Host used by hacker conglomerate traced to Iran.",
            "source": "Phase of Intrusion",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "lastModified": "2021-11-09T13:32:37Z",
            "pinned": false,
            "default": false
        },
        {
            "id": 9,
            "dateAdded": "2021-11-09T06:03:54Z",
            "type": "First Seen",
            "value": "2021-11-07T04:00:35Z",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "lastModified": "2021-11-09T06:03:54Z",
            "pinned": false,
            "default": false
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Specific Indicator Attribute

Send a request in the following format to retrieve data for a specific Indicator Attribute:

GET /v3/indicatorAttributes/{indicatorAttributeId}

For example, the following request will retrieve data for the Indicator Attribute whose ID is 9:

GET /v3/indicatorAttributes/9

JSON Response

{
    "data": {
        "id": 9,
        "dateAdded": "2021-11-09T06:03:54Z",
        "type": "First Seen",
        "value": "2021-11-07T04:00:35Z",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T06:03:54Z",
        "pinned": true,
        "default": false
    },
    "status": "Success"
}

Update Indicator Attributes

The following example illustrates the basic format for updating an Indicator Attribute:

PUT /v3/indicatorAttributes/{indicatorAttributeId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will update the value of the Indicator Attribute whose ID is 10 and make it the default Attribute of its type:

PUT /v3/indicatorAttributes/10
Content-Type: application/json

{
    "default": true,
    "value": "Host used by hacker conglomerate traced to China."
}

JSON Response

{
    "data": {
        "id": 10,
        "dateAdded": "2021-11-09T13:32:37Z",
        "type": "Additional Analysis and Context",
        "value": "Host used by hacker conglomerate traced to China.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T13:38:12Z",
        "pinned": true,
        "default": true
    },
    "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 to the /v3/indicatorAttributes endpoint.

Delete Indicator Attributes

Send a request in the following format to delete an Indicator Attribute:

DELETE /v3/indicatorAttributes/{indicatorAttributeId}

For example, the following request will delete the Indicator Attribute whose ID is 10:

DELETE /v3/indicatorAttributes/10

JSON Response

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

Hint

You can also remove Indicator Attributes from an Indicator by using the mode field on the /v3/indicators endpoint. See Update an Object’s Metadata for more information.