Artifacts Overview

An Artifact in Workflow is any piece of data not captured in a Note that provides information relevant to a Workflow Case that may be useful to an analyst. Potential Artifact types include all ThreatConnect Indicator types, as well as a variety of other data types. Examples of Artifacts include domains, email addresses, log files, emails, PCAP files, screenshots, SIEM event files, and malware documents.

Endpoint: /api/v3/artifacts

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/artifacts endpoint:

OPTIONS /v3/artifacts

👍
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/artifacts endpoint.

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
associatedGroups	A list of Groups associated to the Artifact	Group Object	FALSE	TRUE	{"data": [{"id": 12345}]} {"data": [{"name": "Bad Adversary", "type": "Adversary"}]}
associatedIndicators	A list of Indicators associated to the Artifact	Indicator Object	FALSE	TRUE	{"data": [{"id": 12345}]} {"data": [{"hostName":"badguy.com", "type": "Host"}]}
caseId	The ID of the Case to which the Artifact belongs	Integer	TRUE¹	FALSE	1, 2, 3
caseXid	The XID of the Case to which the Artifact belongs	String	TRUE¹	FALSE	"a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1"
derivedLink	Specifies whether the Artifact should be used to potentially associate Cases	Boolean	FALSE	TRUE	true, false
fieldName²	The name of the Task Artifact Field to which the Artifact corresponds	String	FALSE	TRUE	"senderAddress"
fileData	Base64-encoded file attachment (required only for certain Artifact types)	String	FALSE	TRUE	"UEsDBBQABgAIAA..."
hashCode	The hash code of File-type Artifacts	String	FALSE	FALSE	"C254ZZjosDoUA2B..."
notes	A list of Notes added to the Artifact	Note Object	FALSE	TRUE	{"data": [{"text": "This IP address is malicious."}]}
source	The name of the user who added the Artifact to the Case	String	FALSE	TRUE	"jsmith"
summary	The summary (i.e., name) of the Artifact	String	TRUE	TRUE	"badguy.com"
taskId	The ID of the Task to which the Artifact belongs	Integer	FALSE	FALSE	1, 2, 3
taskXid	The XID of the Task to which the Artifact belongs	String	FALSE	FALSE	"d7dafb59-bf74-46fe-bf18-8da14cc59219"
type³	The Artifact's type	String	TRUE	FALSE	"URL"

1: When adding an Artifact to a Case, you must include either the caseId or caseXid field in the body of the POST request. Only one needs to be included in the body of the POST request, but both can be included, if desired.

2: To retrieve the name of a Task's Artifact Field(s), send a request in the following format and review the name field for each Artifact Field contained within the configTask object in the response: GET /v3/tasks/{taskId}.

3: To retrieve a list of available Artifact types, send the following request and review the type field in the response: OPTIONS /v3/artifacts. You can also retrieve a list of available Artifact types by sending the following request: GET /v3/artifactTypes.

📘
Note
If adding an Artifact to a Task, you do not need to specify the ID of the Case to which the Task belongs in your request. You only need to specify the ID or XID of the Task to which the Artifact will be added.

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/artifacts endpoint:

OPTIONS /v3/artifacts/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/artifacts endpoint:

OPTIONS /v3/artifacts/tql

Create Artifacts

The following example illustrates the basic format for creating an Artifact:

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

{
    "caseId": 1,
    "summary": "Summary of the data contained in the Artifact",
    "type": "The Artifact's data type"
}

For example, the following request will add an Email Address Artifact with a summary of [email protected] to the Case whose ID is 1. It will also complete the following actions for the Artifact:

Create a new Bad Guy Adversary Group and associate it to the Artifact
Add a Note to the Artifact

👍
Hint
To include the associatedGroups and notes fields in the API response, append ?fields=associatedGroups&fields=notes to the end of the request URL.

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

{
    "caseId": 1,
    "summary": "[email protected]",
    "type": "Email Address",
    "associatedGroups": {"data": [{"name": "Bad Guy", "type": "Adversary"}]}, 
    "notes": {"data": [{"text": "This email address belongs to a bad guy."}]}
}

{
    "data": {
        "id": 1,
        "summary": "[email protected]",
        "type": "Email Address",
        "intelType": "indicator-EmailAddress",
        "dateAdded": "2021-04-22T19:24:06Z",
        "derivedLink": true,
        "hashCode": "a/mHEtrRoPrG9csrdltEY73kdKHihi2jow40V3WFYrU="
    },
    "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/artifacts endpoint.

📘
Note
To create an Artifact that is displayed in the Task Artifacts section when viewing the Task in the ThreatConnect UI, the following conditions must be met:

The Artifact must be added to a Task

The Task to which the Artifact is added must have an Artifact Field that accepts the Artifact's type

The fieldname field must be defined when creating the Artifact, and the value for this field must be the Task's Artifact Field that accepts the Artifact's type

If these conditions are not met, the Artifact will be listed as a related Artifact when viewing the Task in the ThreatConnect UI. For more information about Artifact Fields, see the "Artifact Fields" section of the Adding Tasks to a Case knowledge base article.

Retrieve Artifacts

Retrieve All Artifacts

Send the following request to retrieve data for all Artifacts:

GET /v3/artifacts

{
    "data": [
        {
            "id": 1,
            "summary": "[email protected]",
            "type": "Email Address",
            "intelType": "indicator-EmailAddress",
            "dateAdded": "2021-04-22T19:24:06Z",
            "derivedLink": true,
            "hashCode": "a/mHEtrRoPrG9csrdltEY73kdKHihi2jow40V3WFYrU="
        },
        {
            "id": 2,
            "summary": "123.456.78.90",
            "type": "IP Address",
            "intelType": "indicator-Address",
            "source": "johnsmith",
            "dateAdded": "2021-03-08T13:24:38Z",
            "derivedLink": true,
            "hashCode": "cbdb4defdbb9433683a9daa0764c58a45bddd729"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Specific Artifact

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

GET /v3/artifacts/{artifactId}

For example, the following query will return information about the Artifact with ID 3:

GET /v3/artifacts/3

{
    "data": {
        "id": 3,
        "summary": "URGENT - APPROVAL IS REQUIRED!!!",
        "type": "Email Subject",
        "fieldName": "helloSubject",
        "intelType": "indicator-Email Subject",
        "source": "patjones",
        "dateAdded": "2021-03-15T10:16:40Z",
        "derivedLink": true,
        "hashCode": "fec31a1f2937c37b110d467cf78c03d820954596"
    },
    "status": "Success"
}

Update Artifacts

The following example illustrates the basic format for updating an Artifact:

PUT /v3/artifacts/{artifactId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will update the summary of the Artifact whose ID is 1:

PUT /v3/artifacts/1
Content-Type: application/json

{
    "summary": "[email protected]"
}

{
    "data": {
        "id": 1,
        "summary": "[email protected]",
        "type": "Email Address",
        "intelType": "indicator-EmailAddress",
        "dateAdded": "2021-04-22T19:24:06Z",
        "derivedLink": true,
        "hashCode": "bR3jGyx3DqnOrXQ/dI/pYeYOpGOgxalv64tymVN661M="
    },
    "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/artifacts endpoint.

👍
Hint
When updating an Artifact, you can use the mode field to add or remove the following metadata:

associatedGroups

associatedIndicators

See Update an Object's Metadata for instructions on using the mode field.

📘
Note
To update an Artifact's fieldName, the Artifact must belong to a Task, and that Task must contain multiple Artifact Fields that accept the Artifact's type. For more information about Artifact Fields, see the "Artifact Fields" section of the Adding Tasks to a Case knowledge base article.

Delete Artifacts

Send a request in the following format to delete an Artifact:

DELETE /v3/artifacts/{artifactId}

For example, the following request will delete the Artifact whose ID is 1:

DELETE /v3/artifacts/1

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

Delete Artifacts in Bulk

For instructions on deleting Artifacts in bulk, see Delete Case Objects in Bulk.

Associations

For instructions on creating and managing associations for Artifacts, see Create and Manage Associations.