Skip to content

Manage case comments

This page complements the Cases GraphQL API guide. Use it for the comment operations that support the case workflow.

To create a case or resolve its lifecycle values first, see Manage the case lifecycle.

Add, update, search, and delete comments on cases. Comments support @mentions to notify users.

What this covers

This guide shows how to add, update, search, and delete case comments. It also explains visibility filters, mentions, pagination, and sorting.

Prerequisites

  • Create a service principal and get a bearer token. See the Cases GraphQL quickstart.
  • Get the full case ID. The comment mutations do not accept a short case ID.
  • Get user IDs from the Users API before you mention users.

Workflow

Managing case comments with the Cases GraphQL API consists of the following steps:

  1. Add a comment to the case.
  2. Search the comments and check their visibility.
  3. Update or delete comments that you authored.

Add comment

Add a new comment to a case. Comments can include @mentions to notify users.

Mutation

mutation addCaseComment($input: AddCaseComment!) {
    addCaseComment(input: $input) {
        id
        comment
        createdAt
        authorId
        mentionsIds
    }
}

Variables

{
    "input": {
        "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "comment": "Found additional indicators of compromise. @sophos please review."
    }
}

Response example

{
    "data": {
        "addCaseComment": {
            "id": "550e8400-e29b-41d4-a716-446655440300",
            "comment": "Found additional indicators of compromise. @sophos please review.",
            "createdAt": "2024-08-14T16:00:00Z",
            "authorId": "550e8400-e29b-41d4-a716-446655440010",
            "mentionsIds": ["550e8400-e29b-41d4-a716-446655440020"]
        }
    }
}

Notes

  • Comments can include @mentions to notify users.
  • @mentions trigger notifications to the mentioned users.

Update comment

Update an existing comment.

Mutation

mutation updateCaseComment($input: UpdateCaseCommentInput!) {
    updateCaseComment(input: $input) {
        id
        comment
        updatedAt
        authorId
        mentionsIds
    }
}

Variables

{
    "input": {
        "commentId": "550e8400-e29b-41d4-a716-446655440300",
        "comment": "Found additional indicators of compromise and verified malware signatures. @sophos please review.",
        "markAsRead": false
    }
}

Response example

{
    "data": {
        "updateCaseComment": {
            "id": "550e8400-e29b-41d4-a716-446655440300",
            "comment": "Found additional indicators of compromise and verified malware signatures. @sophos please review.",
            "updatedAt": "2024-08-14T16:15:00Z",
            "authorId": "550e8400-e29b-41d4-a716-446655440010",
            "mentionsIds": ["550e8400-e29b-41d4-a716-446655440020"]
        }
    }
}

Notes

  • Only the comment author can update a comment.
  • markAsRead marks the comment as read for the authenticated caller when set to true.
  • Updating a comment with new @mentions triggers new notifications but won't notify users already mentioned again.

Delete comment

Delete an existing comment. Only the comment author can delete a comment.

Mutation

mutation deleteCaseComment($input: DeleteCaseCommentInput!) {
    deleteCaseComment(input: $input) {
        id
    }
}

Variables

{
    "input": {
        "commentId": "550e8400-e29b-41d4-a716-446655440300"
    }
}

Response example

{
    "data": {
        "deleteCaseComment": {
            "id": "550e8400-e29b-41d4-a716-446655440300"
        }
    }
}

Notes

  • This is a hard delete. Data will not be recoverable.
  • Only the comment author can delete a comment.

Search and filter comments

Retrieve comments for a case with pagination.

Query

query caseComments($arguments: CaseCommentsArguments!) {
    caseComments(arguments: $arguments) {
        comments {
            id
            authorId
            createdAt
            updatedAt
            comment
            mentionsIds
            readByIds
            isInternal
        }
        totalCount
        totalUnreadCount
    }
}

Variables

{
    "arguments": {
        "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "orderBy": "DESCENDING",
        "visibility": "ALL",
        "page": 1,
        "perPage": 20
    }
}

Response example

{
    "data": {
        "caseComments": {
            "comments": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440300",
                    "authorId": "550e8400-e29b-41d4-a716-446655440010",
                    "createdAt": "2024-08-14T16:00:00Z",
                    "updatedAt": "2024-08-14T16:15:00Z",
                    "comment": "Found additional indicators of compromise and verified malware signatures.",
                    "mentionsIds": ["550e8400-e29b-41d4-a716-446655440020"],
                    "readByIds": [
                        "550e8400-e29b-41d4-a716-446655440010",
                        "550e8400-e29b-41d4-a716-446655440020"
                    ],
                    "isInternal": false
                },
                {
                    "id": "550e8400-e29b-41d4-a716-446655440301",
                    "authorId": "550e8400-e29b-41d4-a716-446655440020",
                    "createdAt": "2024-08-14T16:05:00Z",
                    "updatedAt": "2024-08-14T16:05:00Z",
                    "comment": "Confirmed. Escalating to SOC team.",
                    "mentionsIds": [],
                    "readByIds": ["550e8400-e29b-41d4-a716-446655440020"],
                    "isInternal": false
                }
            ],
            "totalCount": 2,
            "totalUnreadCount": 0
        }
    }
}

Notes

  • visibility is INTERNAL for internal comments, NOT_INTERNAL for non-internal comments, or ALL for both. The default is ALL.
  • Permissions still apply after the visibility filter. Customer permissions hide internal comments, while partner callers can retrieve them.
  • totalUnreadCount is not affected by pagination or the orderBy filter — it always reflects the case's total unread count for the authenticated caller.

Pagination

Comments support offset-based pagination.

{
    "arguments": {
        "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "page": 1,
        "perPage": 20
    }
}
  • page: 1-indexed page number (default: 1)
  • perPage: Results per page, max 100 (default: 25)

Comment mentions

Mentions in comments notify specific users or groups. Include @mentions in the comment text to trigger notifications.

User and group mentions

User mentions use a user identifier after @. The API accepts UUIDs and other user identifier formats supported by your tenant.

Group mentions use configured tokens, such as @customer or @admin. The API doesn't resolve an arbitrary @username, group UUID, or group display name. Use the exact mention token supplied by your service partner.

Special mentions

Comments support special mentions, which route notifications to specific roles or teams. Availability depends on your tenant type and service level:

Mention When Available Use
@customer Tenant-dependent Notify the customer's organization
@admin Sophos Central XDR tenants with the Cases API Notify administrators
@authorized_contacts Sophos Central tenants with Sophos Managed Detection and Response (MDR) Notify authorized MDR contacts
@sophos Partner-restricted Notify Sophos Support

The @sophos partner-restricted mention may not be available, depending on your service agreement.

Your service partner may define custom mentions specific to your agreement. Contact your partner or account team for available mention options.

Finding user IDs

To find user IDs for your tenant, use the Users API to query available users.

Example with mentions

{
    "input": {
        "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "comment": "@550e8400-e29b-41d4-a716-446655440020 please review. @customer this is for your information."
    }
}

Notes

  • Mentions trigger notifications to the mentioned users or groups.
  • @mentions are extracted from the comment text and added to mentionsIds in the response.
  • Updating a comment with new @mentions triggers notifications to newly mentioned users.
  • Users already mentioned in the previous version of the comment won't be notified again.
  • Mentions notify only recipients allowed by the tenant and caller permissions.

Sorting comments

Sort comments by creation timestamp:

{
    "arguments": {
        "caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "orderBy": "DESCENDING"
    }
}

Sort options:

  • ASCENDING - Oldest first (default if orderBy is omitted)
  • DESCENDING - Newest first

Error handling

Check the HTTP status and the GraphQL response body. A request can return HTTP 200 with an errors array.

Common failures include an unknown case ID, a comment ID from another tenant, and an update or delete by a different author. Check the caller permissions before you retry.

Constraints and considerations

The pagination, deletion, unread-count, and mention constraints appear in the relevant sections above.