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

Create Artifacts

The most 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
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 Artifact with the data type Email Address and a summary of badguy@bad.com for the Case with ID 1.

POST /v3/artifacts/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "summary": "badguy@bad.com",
  "type": "Email Address"
}

JSON Response:

{
  "data": {
      "id": 1,
      "summary": "badguy@bad.com",
      "type": "Email Address",
      "intelType": "indicator-EmailAddress",
      "dateAdded": "2021-04-22T19:24:06Z",
      "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": "badguy@bad.com",
    "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"
  }],
  "count": 2,
  "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 Artifact, refer to the Request Additional Fields for Returned Objects section in this documentation.

Filter Results

To filter returned Artifacts using ThreatConnect Query Language (TQL), refer to the Filter Results with TQL section in this documentation.

Update Artifacts

To update an Artifact, the basic format 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
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": "verybadguy@bad.com"
}

JSON Response:

{
  "data": {
    "id": 1,
    "summary": "verybadguy@bad.com",
    "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 most 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 the Delete Case Objects in Bulk section in this documentation.