Notes

A Note contains 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 each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/notes

Hint

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

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 for the notes object.

Field	Description	Type	Required for Creation?	Updatable?
artifactId	The ID of the Artifact to which the Note will be applied	Integer	FALSE	FALSE
caseId	The ID of the Case to which the Note will be applied	Integer	TRUE*	FALSE
caseXid	The XID of the Case to which the Note will be applied	String	TRUE*	FALSE
taskId	The ID of the Task to which the Note will be applied	Integer	FALSE	FALSE
taskXid	The XID of the Task to which the Note will be applied	String	FALSE	FALSE
text	The contents of the Note	String	TRUE	TRUE
workflowEventId	The ID of the Workflow Event to which the Note will be applied	Integer	FALSE	FALSE

Note

*When creating a Note, either caseId or caseXid must be included 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.

Create Notes

The basic format for creating a Note is:

POST /v3/notes
{
    "caseId": 1,
    "text": "This is an example note."
}

For example, the following query will create a Note for the Case with ID 3.

POST /v3/notes
{
    "caseId": 3,
    "text": "Review the contents of the malware investigation that was recently closed."
}

JSON Response:

{
    "data": {
        "id": 7,
        "caseId": 3,
        "caseXid": "d7dafb59-bf74-46fe-bf18-8da14cc59219",
        "text": "Review the contents of the malware investigation that was recently closed.",
        "summary": "Review the contents of the malware investigation that was recently closed.",
        "author": "11112222333344445555",
        "dateAdded": "2022-04-06T13:14:25Z",
        "lastModified": "2022-04-06T13:14:25Z",
        "edited": false
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields and section for a list of available fields that can be included in the body of a POST request for the notes object.

Retrieve Notes

Retrieve All Notes

To retrieve all Notes, use the following query:

GET /v3/notes

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": 12
        },
        {
            "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,
        "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": 12
    },
    "status": "Success"
}

Request Additional Fields

To request additional fields not automatically included 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 Notes

The basic format for updating a Note is:

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

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

Refer to the Available Fields and section for a list of available fields that can be included in the body of a PUT request for the notes object.

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.