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.

List and create notes

1
2
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 an owned note's label or content
DELETE /notes/{NOTE_ID} Permanently archive an owned 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; access to the command alone does not grant ownership. 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.