Comments & Activity

Comments and activity logs form the collaboration backbone of every ITSM ticket. Comments capture agent notes, customer replies, internal discussions, and AI-generated suggestions. The activity log provides a complete, immutable audit trail of every change made to a ticket throughout its lifecycle.

The comment model

The comment model contains all the information about a comment or note attached to a ticket, including its visibility, type, and any referenced users or attachments.

Properties

Name
id
Type
string
Description
Unique identifier for the comment (UUID).
Name
ticket_id
Type
string
Description
The ID of the ticket this comment belongs to.
Name
author_id
Type
string
Description
The ID of the user who authored the comment.
Name
author_name
Type
string
Description
Display name of the comment author.
Name
body
Type
string
Description
The comment text content. Supports Markdown formatting.
Name
type
Type
string
Description
The comment type. One of comment, internal_note, system, or ai_suggestion.
Name
visibility
Type
string
Description
Who can see this comment. One of public or internal.
Name
attachments
Type
array
Description
An array of attachment objects associated with the comment.
Name
mentions
Type
array
Description
An array of user IDs mentioned in the comment body.
Name
created_at
Type
timestamp
Description
Timestamp of when the comment was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the comment was last updated.

The activity model

The activity model represents a single event in a ticket's audit trail. Activities are system-generated and immutable — they cannot be edited or deleted.

Properties

Name
id
Type
string
Description
Unique identifier for the activity entry (UUID).
Name
ticket_id
Type
string
Description
The ID of the ticket this activity belongs to.
Name
actor_id
Type
string
Description
The ID of the user or system that performed the action.
Name
actor_name
Type
string
Description
Display name of the actor.
Name
action
Type
string
Description
The action that occurred. One of created, updated, commented, assigned, escalated, resolved, or sla_breached.
Name
field_changed
Type
string
Description
The name of the field that was modified, if applicable (e.g., status, priority, assignee_id).
Name
old_value
Type
string
Description
The previous value of the changed field.
Name
new_value
Type
string
Description
The new value of the changed field.
Name
timestamp
Type
timestamp
Description
Timestamp of when the activity occurred.

GET/v1/tickets/:ticketId/comments

List all comments

This endpoint allows you to retrieve a paginated list of all comments on a ticket. By default, a maximum of twenty comments are shown per page, ordered by creation time ascending.

Optional attributes

Name
type
Type
string
Description
Filter comments by type (e.g., comment, internal_note, ai_suggestion).
Name
visibility
Type
string
Description
Filter by visibility. One of public or internal.
Name
page
Type
integer
Description
The page number for pagination.
Name
limit
Type
integer
Description
Limit the number of comments returned per page.

Request

GET

/v1/tickets/:ticketId/comments

curl -G http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments \
  -H "Authorization: Bearer {token}" \
  -d visibility=public \
  -d limit=20

Response

{
  "has_more": false,
  "page": 1,
  "limit": 20,
  "data": [
    {
      "id": "cmt_d4e5f6a7-b8c9-0123-def0-456789012345",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "author_id": "usr_f6e5d4c3b2a1",
      "author_name": "Jane Rivera",
      "body": "I've checked the VPN gateway logs and see intermittent DTLS handshake failures. Escalating to the network infrastructure team for deeper analysis.",
      "type": "comment",
      "visibility": "public",
      "attachments": [],
      "mentions": [],
      "created_at": 1708784400,
      "updated_at": 1708784400
    },
    {
      "id": "cmt_e5f6a7b8-c9d0-1234-ef01-567890123456",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "author_id": "system",
      "author_name": "AI Assistant",
      "body": "Based on similar resolved incidents, this may be related to MTU mismatch after the recent firewall firmware upgrade. Recommended KB: KB-00891.",
      "type": "ai_suggestion",
      "visibility": "internal",
      "attachments": [],
      "mentions": [],
      "created_at": 1708784500,
      "updated_at": 1708784500
    }
  ]
}

POST/v1/tickets/:ticketId/comments

Add a comment

This endpoint allows you to add a new comment to a ticket. You must provide the comment body at minimum. The author is determined from the authenticated user's JWT token. Internal notes are only visible to agents within your organization.

Required attributes

Name
body
Type
string
Description
The comment text content. Supports Markdown formatting.

Optional attributes

Name
type
Type
string
Description
The comment type. Defaults to comment. One of comment, internal_note, system, or ai_suggestion.
Name
visibility
Type
string
Description
Who can see this comment. Defaults to public. One of public or internal.
Name
attachments
Type
array
Description
An array of attachment objects to include with the comment.
Name
mentions
Type
array
Description
An array of user IDs to mention in the comment.

Request

POST

/v1/tickets/:ticketId/comments

curl http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Confirmed the MTU mismatch theory. Adjusting the tunnel MTU from 1500 to 1400 on the GlobalProtect gateway. Will monitor for 30 minutes.",
    "type": "comment",
    "visibility": "public",
    "mentions": ["usr_a1b2c3d4e5f6"]
  }'

Response

{
  "id": "cmt_f6a7b8c9-d0e1-2345-f012-678901234567",
  "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "author_id": "usr_f6e5d4c3b2a1",
  "author_name": "Jane Rivera",
  "body": "Confirmed the MTU mismatch theory. Adjusting the tunnel MTU from 1500 to 1400 on the GlobalProtect gateway. Will monitor for 30 minutes.",
  "type": "comment",
  "visibility": "public",
  "attachments": [],
  "mentions": ["usr_a1b2c3d4e5f6"],
  "created_at": 1708790400,
  "updated_at": 1708790400
}

GET/v1/tickets/:ticketId/comments/:id

Retrieve a comment

This endpoint allows you to retrieve a specific comment by providing the ticket ID and comment ID. Refer to the comment model at the top of this page to see which properties are included with comment objects.

Request

GET

/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/cmt_d4e5f6a7-b8c9-0123-def0-456789012345

curl http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/cmt_d4e5f6a7-b8c9-0123-def0-456789012345 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "cmt_d4e5f6a7-b8c9-0123-def0-456789012345",
  "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "author_id": "usr_f6e5d4c3b2a1",
  "author_name": "Jane Rivera",
  "body": "I've checked the VPN gateway logs and see intermittent DTLS handshake failures. Escalating to the network infrastructure team for deeper analysis.",
  "type": "comment",
  "visibility": "public",
  "attachments": [],
  "mentions": [],
  "created_at": 1708784400,
  "updated_at": 1708784400
}

PATCH/v1/tickets/:ticketId/comments/:id

Update a comment

This endpoint allows you to edit an existing comment. Only the original author or an admin can update a comment. System-generated comments and activity entries cannot be edited.

Optional attributes

Name
body
Type
string
Description
Updated comment text content.
Name
visibility
Type
string
Description
Update the comment visibility. One of public or internal.
Name
mentions
Type
array
Description
Updated array of user IDs mentioned in the comment.

Request

PATCH

/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/cmt_d4e5f6a7-b8c9-0123-def0-456789012345

curl -X PATCH http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/cmt_d4e5f6a7-b8c9-0123-def0-456789012345 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Updated: DTLS handshake failures confirmed. Root cause is MTU mismatch after firewall firmware upgrade to PAN-OS 11.1.2.",
    "mentions": ["usr_a1b2c3d4e5f6", "usr_b2c3d4e5f6a7"]
  }'

Response

{
  "id": "cmt_d4e5f6a7-b8c9-0123-def0-456789012345",
  "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "author_id": "usr_f6e5d4c3b2a1",
  "author_name": "Jane Rivera",
  "body": "Updated: DTLS handshake failures confirmed. Root cause is MTU mismatch after firewall firmware upgrade to PAN-OS 11.1.2.",
  "type": "comment",
  "visibility": "public",
  "attachments": [],
  "mentions": ["usr_a1b2c3d4e5f6", "usr_b2c3d4e5f6a7"],
  "created_at": 1708784400,
  "updated_at": 1708791000
}

DELETE/v1/tickets/:ticketId/comments/:id

Delete a comment

This endpoint allows you to delete a comment from a ticket. Only the original author or an admin can delete a comment. System-generated comments cannot be deleted. A deletion activity entry is recorded in the ticket's audit trail.

Request

DELETE

/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/cmt_d4e5f6a7-b8c9-0123-def0-456789012345

curl -X DELETE http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/comments/cmt_d4e5f6a7-b8c9-0123-def0-456789012345 \
  -H "Authorization: Bearer {token}"

GET/v1/tickets/:ticketId/activity

Get activity log

This endpoint returns the full activity log for a ticket, including comments, status changes, assignments, escalations, and SLA events. The activity log is an immutable audit trail — entries cannot be modified or deleted. Results are ordered by timestamp ascending.

Optional attributes

Name
action
Type
string
Description
Filter activities by action type (e.g., assigned, escalated, sla_breached).
Name
actor_id
Type
string
Description
Filter activities by the actor who performed the action.
Name
page
Type
integer
Description
The page number for pagination.
Name
limit
Type
integer
Description
Limit the number of activity entries returned per page.

Request

GET

/v1/tickets/:ticketId/activity

curl -G http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/activity \
  -H "Authorization: Bearer {token}" \
  -d limit=50

Response

{
  "has_more": false,
  "page": 1,
  "limit": 50,
  "data": [
    {
      "id": "act_a1b2c3d4-e5f6-7890-abcd-000000000001",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "actor_id": "usr_a1b2c3d4e5f6",
      "actor_name": "Carlos Mendez",
      "action": "created",
      "field_changed": null,
      "old_value": null,
      "new_value": null,
      "timestamp": 1708783200
    },
    {
      "id": "act_a1b2c3d4-e5f6-7890-abcd-000000000002",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "actor_id": "system",
      "actor_name": "AI Triage",
      "action": "updated",
      "field_changed": "priority",
      "old_value": null,
      "new_value": "high",
      "timestamp": 1708783201
    },
    {
      "id": "act_a1b2c3d4-e5f6-7890-abcd-000000000003",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "actor_id": "usr_f6e5d4c3b2a1",
      "actor_name": "Jane Rivera",
      "action": "assigned",
      "field_changed": "assignee_id",
      "old_value": null,
      "new_value": "usr_f6e5d4c3b2a1",
      "timestamp": 1708783500
    },
    {
      "id": "act_a1b2c3d4-e5f6-7890-abcd-000000000004",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "actor_id": "usr_f6e5d4c3b2a1",
      "actor_name": "Jane Rivera",
      "action": "commented",
      "field_changed": null,
      "old_value": null,
      "new_value": "cmt_d4e5f6a7-b8c9-0123-def0-456789012345",
      "timestamp": 1708784400
    },
    {
      "id": "act_a1b2c3d4-e5f6-7890-abcd-000000000005",
      "ticket_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "actor_id": "system",
      "actor_name": "SLA Engine",
      "action": "sla_breached",
      "field_changed": "sla_response_due_at",
      "old_value": "1708786800",
      "new_value": "breached",
      "timestamp": 1708786801
    }
  ]
}