Artifacts

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

Available Fields

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

OPTIONS /v3/artifacts

Note

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

Create Artifacts

The basic format for creating an Artifact is:

POST /v3/artifacts/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "summary": "Summary of the data contained in the Artifact",
  "type": "The Artifact's data type"
}

Some Artifact types require additional fields when being created. Refer to the following table for a list of available fields for the artifacts object:

Field	Description	Required	Type
caseId	The ID of the Case that contains the Artifact	TRUE	Integer
caseXid	The XID of the Case that contains the Artifact	TRUE	String
derivedLink	Specifies whether the Artifact should be used to potentially associate Cases	FALSE	Boolean
fieldName	The name of the Artifact Field within an associated Task	FALSE	String
fileData	Base64-encoded file attachment (required only for certain Artifact types)	FALSE	String
hashCode	The hash code of File-type Artifacts	FALSE	String
notes	A list of Notes corresponding to the Artifact	FALSE	String
source	The name of the user who entered the Artifact into the Case	FALSE	String
summary	The data contained in the Artifact	TRUE	String
taskId	The ID of the Task that the Artifact references	FALSE	Integer
taskXid	The XID of the Task that the Artifact references	FALSE	String
type	The Artifact’s data type	TRUE	String

Note

To view a list of available Artifact data types, use the following query and refer to the type field:

OPTIONS /v3/artifacts/

Alternatively, refer to Artifact Types section in this documentation.

Hint

To create an Artifact that is displayed in the Task Artifacts section of a Task, the Artifact must be associated with a Task, the associated Task must have an Artifact Field defined that accepts the same Artifact data type as the associated Artifact, and the fieldname field must be defined. Otherwise, the Artifact will be displayed in the Related Artifacts section of the Task. For more information about Artifact Fields, see the “Artifact Fields” section of Workflow Cases.

For example, the following query will create an Email Address Artifact with a summary of badguy@bad.com for the Case with ID 1 and create a Note for the Artifact:

POST /v3/artifacts/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "summary": "[email protected]",
  "type": "Email Address",
  "notes": {"data": [{"text": "Note about this artifact"}]}
}

JSON Response:

{
  "data": {
      "id": 1,
      "summary": "[email protected]",
      "type": "Email Address",
      "intelType": "indicator-EmailAddress",
      "dateAdded": "2021-04-22T19:24:06Z",
      "notes": {
            "data": [
                {
                    "id": 5,
                    "text": "Note about this artifact",
                    "summary": "Note about this artifact",
                    "author": "APIuser",
                    "dateAdded": "2021-04-22T19:24:06Z",
                    "lastModified": "2021-04-22T19:24:06Z",
                    "edited": false,
                    "artifactId": 1
                }
            ]
      },
      "derivedLink": true,
      "hashCode": "bR3jGyx3DqnOrXQ/dI/pYeYOpGOgxalv64tymVN661M="
  },
  "message": "Created",
  "status": "Success"
}

Retrieve Artifacts

Retrieve All Artifacts

To retrieve all Artifacts, use the following query:

GET /v3/artifacts/

JSON Response:

{
  "data": [{
    "id": 1,
    "summary": "[email protected]",
    "type": "Email Address",
    "fieldName": "helloRecipient",
    "intelType": "indicator-EmailAddress",
    "source": "11112222333344445555",
    "dateAdded": "2021-04-22T19:24:06Z",
    "derivedLink": true,
    "hashCode": "2e7d3603331dea4ec9a14442c0a409dcfc3f69e7"
  }, {
    "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 Single Artifact

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

GET /v3/artifacts/{artifactId}

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

GET /v3/artifacts/3

JSON Response:

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

Request Additional Fields

To request additional fields not automatically provided 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 Artifacts

The basic format for updating an Artifact is:

PUT /v3/artifacts/{artifactId}
{
    {updatedField}: {updatedValue}
}

Refer to the following table for a list of available fields that can be updated for the artifacts object:

Field	Description	Type
derivedLink	Specifies whether the Artifact should be used to potentially associate Cases	Boolean
fieldName	The name of the Artifact Field within an associated Task	String
fileData	Base64-encoded file attachment (required only for certain Artifact types)	String
notes	A list of Notes corresponding to the Artifact	String
source	The name of the user who entered the Artifact into the Case	String
summary	The data contained in the Artifact	String

Note

To update an Artifact’s fieldName, the Artifact must be associated with a Task, and the associated Task must have multiple Artifact Fields defined. For more information about Artifact Fields, see the “Artifact Fields” section of Workflow Cases.

For example, the query below will update the summary for the Artifact with ID 1.

PUT /v3/artifacts/1
{
  "summary": "[email protected]"
}

JSON Response:

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

Delete Artifacts

The basic format to delete an Artifact is:

DELETE /v3/artifacts/{artifactId}

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

DELETE /v3/artifacts/1

JSON Response:

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

Delete Artifacts in Bulk

To delete Artifacts in bulk, refer to Delete Case Objects in Bulk.