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.