Notes Overview

Notes contain freeform information entered by a user and can be added to Artifacts, Cases, and Tasks. They enable security teams to journal key data findings in an unstructured format and can be used to provide commentary, directives to another user, additional details, or any information that cannot be captured elsewhere.

Endpoint: /api/v3/notes

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field's name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/notes endpoint:

OPTIONS /v3/notes

👍
Hint
To include read-only fields in the response, append ?show=readonly to the end of the request URL.

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 to the /v3/notes endpoint.

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

1: When adding a Note to a Case, you must include either the caseId or caseXid field 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.

2: When adding a Note to an Artifact or Task, you do not need to include the caseId or caseXid field in the body of the POST request.

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/notes endpoint:

OPTIONS /v3/notes/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/notes endpoint:

OPTIONS /v3/notes/tql

Create Notes

The following example illustrates the basic format for creating a Note:

POST /v3/notes
Content-Type: application/json

{
    "caseId": 1,
    "text": "This is an example note."
}

For example, the following request will add a Note to the Case whose ID is 3:

POST /v3/notes
Content-Type: application/json

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

{
    "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 section for a list of available fields that can be included in the body of a POST request to the /v3/notes endpoint.

Retrieve Notes

Retrieve All Notes

Send the following request to retrieve data for all Notes:

GET /v3/notes

{
  "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 Specific Note

Send a request in the following format to retrieve data for a specific Note:

GET /v3/notes/{noteId}

For example, the following request will retrieve data for the Note whose ID is 1:

GET /v3/notes/1

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

Update Notes

The following example illustrates the basic format for updating a Note:

PUT /v3/notes/{noteId}
Content-Type: application/json

{
    "text": "{updatedNoteContents}"
}

For example, the following request will update the contents of the Note whose ID is 2:

PUT /v3/notes/2
Content-Type: application/json

{
    "text": "More detailed notes about a phishing threat."
}

{
    "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 section for a list of available fields that can be included in the body of a PUT request to the /v3/notes endpoint.

Delete Notes

Send a request in the following format to delete a Note:

DELETE /v3/notes/{noteId}

For example, the following request will delete the Note whose ID is 1:

DELETE /v3/notes/1

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

Delete Notes in Bulk

For instructions on deleting Notes in bulk, refer to Delete Case Objects in Bulk.