Notes

A Note in Workflow is freeform information entered by a user (e.g., in a Case or attached to a Task or Artifact). Notes can be used to provide commentary, directives to another user, additional details, or any information that cannot be captured elsewhere. They enable security teams to journal key data findings in an unstructured format.

Endpoint: /api/v3/notes

Available Fields

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

OPTIONS /v3/notes

Note

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

Retrieve Notes

Retrieve All Notes

To retrieve all Notes, use the following query:

GET /v3/notes/

JSON Response:

{
  "data": [{
    "id": 1,
    "caseId": 1,
    "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
    "text": "Some notes about a case artifact.",
    "summary": "Some notes about a case artifact.",
    "author": "11112222333344445555",
    "dateAdded": "2021-04-22T20:17:15Z",
    "lastModified": "2021-04-22T20:17:15Z",
    "edited": false
  }, {
    "id": 2,
    "caseId": 2,
    "caseXid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
    "text": "Some notes about a phishing threat.",
    "summary": "Some notes about a phishing threat.",
    "author": "[email protected]",
    "dateAdded": "2021-03-17T10:15:02Z",
    "lastModified": "2021-03-18T09:31:22Z",
    "edited": true
  }],
  "status": "Success"
}

Retrieve a Single Note

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

GET /v3/notes/{noteID}

For example, the following query will return information about the Note with ID 1:

GET /v3/notes/1

JSON Response:

{
  "data": {
    "id": 1,
    "caseId": 1,
    "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
    "text": "Some notes about a phishing threat.",
    "summary": "Some notes about a phishing threat.",
    "author": "11112222333344445555",
    "dateAdded": "2021-04-22T20:17:15Z",
    "lastModified": "22021-04-22T20:17:15Z",
    "edited": false
  },
  "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.

Create Notes

The basic format for creating a Note is:

POST /v3/notes/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "text": "This is an example note."
}

Refer to the following table for a list of available fields for the notes object:

Field Description Required Type
artifactId The ID of the Artifact on which to apply the Note FALSE Integer
caseId The ID of the Case on which to apply the Note TRUE Integer
caseXid The XID of the Case on which to apply the Note TRUE String
taskId The ID of the Task on which to apply the Note FALSE Integer
taskXid The XID of the Task on which to apply the Note FALSE String
text The contents of the Note itself TRUE String
workflowEventId The ID of the Event on which to apply the Note FALSE Integer

For example, the following query will create a Note for the Case with ID 1 and apply it to the Artifact with ID 4.

POST /v3/notes/
{
  "caseId": 1,
  "caseXid": "aa1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "text": "Some notes about a case artifact.",
  "artifactId": 4
}

JSON Response:

{
  "data": {
      "id": 1,
      "text": "Some notes about a case artifact.",
      "summary": "Some notes about a case artifact.",
      "author": "11112222333344445555",
      "dateAdded": "2021-04-22T20:17:15Z",
      "lastModified": "2021-04-22T20:17:15Z",
      "edited": false,
      "artifactId": 4
  },
  "message": "Created",
  "status": "Success"
}

Update Notes

The basic format for updating a Note is:

PUT /v3/notes/{noteID}
{
    {updatedField}: {updatedValue}
}

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

Field Description Required Type
text The contents of the Note itself TRUE String

For example, the following query will update the contents of the Note with ID 2:

PUT /v3/notes/2
{
  "text": "More detailed notes about a phishing threat."
}

JSON Response:

{
  "data": {
    "id": 2,
    "caseId": 2,
    "caseXid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
    "text": "More detailed notes about a phishing threat.",
    "summary": "More detailed notes about a phishing threat.",
    "author": "[email protected]",
    "dateAdded": "2021-03-17T10:15:02Z",
    "lastModified": "2021-03-18T09:31:22Z",
    "edited": true
  },
  "message": "Updated",
  "status": "Success"
}

Delete Notes

The basic format to delete a Note is:

DELETE /v3/notes/{noteID}

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

DELETE /v3/notes/1

JSON Response:

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

Delete Cases in Bulk

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