Skip to content

API: Command Notes

Command notes attach a label and text to a command. Notes have ownership controls and audit events, and can be archived without removing their history. These endpoints require a Bearer token and access to the command. Creating, editing, and archiving notes also requires the SEND_COMMANDS authority.

List and create notes

GET /api/v2/agents/{AGENT_GUID}/commands/{COMMAND_ID}/notes HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

The response is paged and ordered oldest first. page defaults to 0; pageSize defaults to 100 with a range of 1 to 1000. Use label for an exact, case-sensitive label filter, and includeArchived=true to include archived notes. Archived notes are excluded by default.

1
2
3
4
5
6
7
8
POST /api/v2/agents/{AGENT_GUID}/commands/{COMMAND_ID}/notes HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "label": "review",
  "content": "Results reviewed for the exercise report."
}

label and content are required and must contain non-whitespace text. The maximum lengths are 128 and 2000 characters, respectively. A successful creation returns 200 with the note.

Read, edit, and archive a note

Method Path suffix Action
GET /notes/{NOTE_ID} Read a note, including an archived note
PATCH /notes/{NOTE_ID} Change a note's label or content
DELETE /notes/{NOTE_ID} Archive a note

Each suffix extends /api/v2/agents/{AGENT_GUID}/commands/{COMMAND_ID}. NOTE_ID is a UUID. The caller must own a note to edit or archive it, unless they have MANAGE_USERS. The ownership override does not replace the endpoint's SEND_COMMANDS requirement. Access to the command alone does not grant editing rights. Archiving cannot be undone, and archived notes cannot be edited.

For example, change only the content:

1
2
3
4
5
6
7
PATCH /api/v2/agents/{AGENT_GUID}/commands/{COMMAND_ID}/notes/{NOTE_ID} HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "content": "Review complete; findings added to the exercise report."
}

The response includes the note's id, command target, label, content, status (ACTIVE or ARCHIVED), createEvent, lastUpdateEvent, and nullable archiveEvent. See audit actors for event attribution.

Command notes are also available through tse.notes in server-side Python scripts.