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

[1]	When setting the `type` field, you must enter a valid Attribute Type that applies to the type of Indicator to which the Attribute is being added. To retrieve a list of available Attribute Types, send the following request: `GET /v3/attributeTypes`.

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
{
    "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
{
    "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}
{
    {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
{
    "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.