Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Comments

APIs for managing report comments

Add a comment to an MTH/MDR report

post

Adds a new comment to an MTH/MDR report from a child tenant.

Validation rules:

  • xsoar_source_id is required and must be a non-empty string.

  • comment_text is required, must be a string, and is limited to 4096 characters by the API (the underlying column is VARCHAR(4096)).

  • comment_created_by is required and must be a non-empty string. It is not validated against tenant users.

  • path_to_file is optional. When supplied it must be a key already present in the public API GCS bucket and must begin with one of the allowed prefixes: send_report/, update_report/, add_comment/, update_comment/, comment/. Keys containing .. or starting with / are rejected.

  • extract_zip_file is optional and must be a string. Only the values "true" (case-insensitive) and "1" enable extraction; every other value, including the JSON boolean true, is treated as false.

Notes:

  • If xsoar_source_id does not match an existing report, a generic error response is returned.

  • The comment is always recorded with comment_author_type = CUSTOMER (is_hunter is forced to false on this endpoint).

  • comment_username is taken from the authenticated API key's user, not from comment_created_by.

Required licenses: MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.

Permissions: Users with Instance Administrator privileges only can access these endpoints.

Authorizations
AuthorizationstringRequired

API Key for authentication

x-xdr-auth-idstringRequired

API Key ID for authentication

Header parameters
AuthorizationstringRequired

{api_key}

Example: YOUR_API_KEY_HERE
x-xdr-auth-idstringRequired

{api_key_id}

Example: 241
Body
xsoar_source_idstringRequired

The unique identifier of the report to comment on

comment_textstring · max: 4096Required

The text content of the comment (maximum 4096 characters).

comment_created_bystringRequired

Email or username of the comment author. Free text; not validated against tenant users.

path_to_filestringOptional

Optional storage key of an attachment already uploaded to the public API GCS bucket. Must start with one of: send_report/, update_report/, add_comment/, update_comment/, comment/.

extract_zip_filestring · enumOptional

Optional flag indicating the attachment is a zip archive to be extracted. Must be a string; only "true" (case-insensitive) or "1" enable extraction. A JSON boolean is rejected by type validation.

Possible values:
Responses
200

Successful Response

application/json
replybooleanOptional

true when the comment was added successfully. Failures are returned as an error response, not as false.

post/public_api/v1/mth/child/add_comment
POST /public_api/v1/mth/child/add_comment HTTP/1.1
Host: api-yourfqdn
Authorization: YOUR_API_KEY_HERE
x-xdr-auth-id: 241
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "xsoar_source_id": "777771",
  "comment_text": "Investigation completed. No malicious activity found.",
  "comment_created_by": "analyst@company.com"
}
{
  "reply": true
}

Get comments for MTH/MDR reports

post

Retrieves comments for a specific report or for all comments within a specified time range.

Validation rules:

  • Supply either xsoar_source_id, or both start_time and end_time.

  • xsoar_source_id takes precedence: if it is present, start_time/end_time are ignored.

  • start_time and end_time must both be integers; supplying only one of them is equivalent to supplying neither.

  • start_time must be less than or equal to end_time.

  • If no usable criteria are supplied, the request fails.

Response notes:

  • comment_attachments is an array of pre-signed download URLs (strings), not a JSON-encoded object. It is [] when the comment has no attachments.

  • comment_author_type is the raw numeric column value: 0 = hunter-authored, 1 = customer-authored. It is not returned as the string "HUNTER"/"CUSTOMER".

  • Timestamps are integers in epoch milliseconds. comment_update_time is null when the comment was never edited.

Required licenses: MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.

Permissions: Users with Instance Administrator privileges only can access these endpoints.

Authorizations
AuthorizationstringRequired

API Key for authentication

x-xdr-auth-idstringRequired

API Key ID for authentication

Header parameters
AuthorizationstringRequired

{api_key}

Example: YOUR_API_KEY_HERE
x-xdr-auth-idstringRequired

{api_key_id}

Example: 241
Body

Supply either xsoar_source_id, or both start_time and end_time. If xsoar_source_id is present the time range is ignored.

xsoar_source_idstringOptional

The unique identifier of the report

start_timeinteger · int64Optional

Start timestamp in epoch milliseconds. Must be supplied together with end_time and must not be greater than it.

end_timeinteger · int64Optional

End timestamp in epoch milliseconds. Must be supplied together with start_time.

Responses
200

Successful Response

application/json
post/public_api/v1/mth/child/get_comments
POST /public_api/v1/mth/child/get_comments HTTP/1.1
Host: api-yourfqdn
Authorization: YOUR_API_KEY_HERE
x-xdr-auth-id: 241
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "xsoar_source_id": "777772"
}
{
  "reply": {
    "status": true,
    "data": [
      {
        "comment_id": 7,
        "comment_created_by": "stam_updated_user",
        "comment_author_type": 1,
        "comment_insert_time": 1763468552000,
        "comment_update_time": 1763468849000,
        "comment_text": "Update comment stam",
        "comment_attachments": [],
        "xsoar_source_id": "777771",
        "comment_username": "customer.user@company.com"
      },
      {
        "comment_id": 21,
        "comment_created_by": "Unit42 Threat Hunting",
        "comment_author_type": 0,
        "comment_insert_time": 1763468843000,
        "comment_update_time": null,
        "comment_text": "Hunter follow-up",
        "comment_attachments": [],
        "xsoar_source_id": "777771",
        "comment_username": "analyst@company.com"
      },
      {
        "comment_id": 34,
        "comment_created_by": "iavron iavron",
        "comment_author_type": 1,
        "comment_insert_time": 1764235743000,
        "comment_update_time": null,
        "comment_text": "Attachment test",
        "comment_attachments": [
          "https://test-bucket.storage.googleapis.com/comment/Screenshot.png-1764235743000?Expires=1765122615&GoogleAccessId=api-pod%40example.iam.gserviceaccount.com&Signature=REDACTED"
        ],
        "xsoar_source_id": "484485",
        "comment_username": "iavron@example.com"
      }
    ]
  }
}
PreviousAssignment
NextReports

Last updated

Was this helpful?