> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/managed-services/comments.md). # Comments APIs for managing report comments ## Add a comment to an MTH/MDR report > 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. ```json {"openapi":"3.0.1","info":{"title":"Managed Services APIs","version":"1.0.1"},"tags":[{"name":"Comments","description":"APIs for managing report comments"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"AddCommentRequestData":{"type":"object","required":["xsoar_source_id","comment_text","comment_created_by"],"properties":{"xsoar_source_id":{"type":"string","description":"The unique identifier of the report to comment on"},"comment_text":{"type":"string","maxLength":4096,"description":"The text content of the comment (maximum 4096 characters)."},"comment_created_by":{"type":"string","description":"Email or username of the comment author. Free text; not validated against tenant users."},"path_to_file":{"type":"string","description":"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_file":{"type":"string","description":"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.","enum":["true","false","1","0"]}}},"AddCommentResponse":{"type":"object","properties":{"reply":{"type":"boolean","description":"`true` when the comment was added successfully. Failures are returned as an error response, not as `false`."}}},"BaseError":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Numeric error code, mirroring the HTTP status code. Most validation and business-logic failures on these endpoints return 500."},"err_msg":{"type":"string","description":"Generic error message, for example `An error occurred while processing XDR public API`."},"err_extra":{"type":"string","nullable":true,"description":"Specific reason for the failure. This is the field to inspect when diagnosing a rejected request."}}}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Forbidden":{"description":"Forbidden - Tenant not authorized for this endpoint, or the caller lacks Instance Administrator privileges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"InternalServerError":{"description":"Internal Server Error.\n\nNote: most business-logic and input-validation failures on these endpoints are also returned with HTTP 500 and `reply.err_code` 500, with the specific reason in `reply.err_extra`. Do not rely on a 400 status to detect a bad request; inspect `reply.err_extra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}}}},"paths":{"/public_api/v1/mth/child/add_comment":{"post":{"summary":"Add a comment to an MTH/MDR report","operationId":"postAddComment","description":"Adds a new comment to an MTH/MDR report from a child tenant.\n\n**Validation rules:**\n- `xsoar_source_id` is required and must be a non-empty string.\n- `comment_text` is required, must be a string, and is limited to **4096 characters** by the API (the underlying column is `VARCHAR(4096)`).\n- `comment_created_by` is required and must be a non-empty string. It is **not** validated against tenant users.\n- `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.\n- `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`.\n\n**Notes:**\n- If `xsoar_source_id` does not match an existing report, a generic error response is returned.\n- The comment is always recorded with `comment_author_type = CUSTOMER` (`is_hunter` is forced to `false` on this endpoint).\n- `comment_username` is taken from the authenticated API key's user, not from `comment_created_by`.\n\n**Required licenses:** MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\n\n**Permissions:** Users with Instance Administrator privileges only can access these endpoints.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"description":"Request body for adding a comment to an MTH/MDR report.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCommentRequestData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCommentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Comments"]}}}} ``` ## Get comments for MTH/MDR reports > 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. ```json {"openapi":"3.0.1","info":{"title":"Managed Services APIs","version":"1.0.1"},"tags":[{"name":"Comments","description":"APIs for managing report comments"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"GetCommentsRequestData":{"type":"object","description":"Supply either `xsoar_source_id`, or both `start_time` and `end_time`. If `xsoar_source_id` is present the time range is ignored.","properties":{"xsoar_source_id":{"type":"string","description":"The unique identifier of the report"},"start_time":{"type":"integer","format":"int64","description":"Start timestamp in epoch milliseconds. Must be supplied together with `end_time` and must not be greater than it."},"end_time":{"type":"integer","format":"int64","description":"End timestamp in epoch milliseconds. Must be supplied together with `start_time`."}}},"GetCommentsResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"status":{"type":"boolean","description":"Operation success status"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"},"description":"Array of comment objects matching the query"}}}}},"Comment":{"type":"object","description":"Standalone comment object returned by `get_comments`. Keys are lower_snake_case.","properties":{"comment_id":{"type":"integer","description":"Unique identifier of the comment"},"comment_created_by":{"type":"string","description":"Free-text author identifier supplied when the comment was created. Not validated and not necessarily an email."},"comment_author_type":{"type":"integer","description":"Numeric author type: `0` = hunter/analyst authored, `1` = customer authored. Returned as an integer, not a string.","enum":[0,1]},"comment_insert_time":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds (epoch)"},"comment_update_time":{"type":"integer","format":"int64","nullable":true,"description":"Last update timestamp in epoch milliseconds, or null if never edited"},"comment_text":{"type":"string","nullable":true,"description":"Text content of the comment"},"comment_attachments":{"type":"array","items":{"type":"string","format":"uri"},"description":"Array of time-limited pre-signed download URLs, one per attachment. Empty array when the comment has no attachments. This is **not** a JSON-encoded object."},"xsoar_source_id":{"type":"string","description":"Source ID of the associated report"},"comment_username":{"type":"string","nullable":true,"description":"User name of the account that created the comment"}}},"BaseError":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Numeric error code, mirroring the HTTP status code. Most validation and business-logic failures on these endpoints return 500."},"err_msg":{"type":"string","description":"Generic error message, for example `An error occurred while processing XDR public API`."},"err_extra":{"type":"string","nullable":true,"description":"Specific reason for the failure. This is the field to inspect when diagnosing a rejected request."}}}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"Forbidden":{"description":"Forbidden - Tenant not authorized for this endpoint, or the caller lacks Instance Administrator privileges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}},"InternalServerError":{"description":"Internal Server Error.\n\nNote: most business-logic and input-validation failures on these endpoints are also returned with HTTP 500 and `reply.err_code` 500, with the specific reason in `reply.err_extra`. Do not rely on a 400 status to detect a bad request; inspect `reply.err_extra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseError"}}}}}},"paths":{"/public_api/v1/mth/child/get_comments":{"post":{"summary":"Get comments for MTH/MDR reports","operationId":"postGetComments","description":"Retrieves comments for a specific report or for all comments within a specified time range.\n\n**Validation rules:**\n- Supply either `xsoar_source_id`, or **both** `start_time` and `end_time`.\n- `xsoar_source_id` takes precedence: if it is present, `start_time`/`end_time` are ignored.\n- `start_time` and `end_time` must both be integers; supplying only one of them is equivalent to supplying neither.\n- `start_time` must be less than or equal to `end_time`.\n- If no usable criteria are supplied, the request fails.\n\n**Response notes:**\n- `comment_attachments` is an **array of pre-signed download URLs (strings)**, not a JSON-encoded object. It is `[]` when the comment has no attachments.\n- `comment_author_type` is the **raw numeric column value**: `0` = hunter-authored, `1` = customer-authored. It is not returned as the string `\"HUNTER\"`/`\"CUSTOMER\"`.\n- Timestamps are integers in epoch milliseconds. `comment_update_time` is `null` when the comment was never edited.\n\n**Required licenses:** MDR, MTH, Managed XSIAM Pro, Managed XSIAM Premium.\n\n**Permissions:** Users with Instance Administrator privileges only can access these endpoints.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"description":"Request body for retrieving comments for MTH/MDR reports.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCommentsRequestData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCommentsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Comments"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/xsiam-api/managed-services/comments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.