{ "openapi": "3.0.1", "x-hideTryItPanel": true, "info": { "version": "1.0.1", "title": "Managed Services APIs", "description": "Public endpoints are provided for MTH (Managed Threat Hunting) and MDR (Managed Detection and Response) child tenants to manage reports, comments, and assignment-related operations.\n\n**Authentication:** All endpoints require API key based authentication using the x-xdr-auth-id and Authorization headers.\n\n**Supported tenants:** Access is limited to MTH Child and MDR Child tenants only. Requests from any other tenant type fail with a generic error.\n\n**Timestamps:** All timestamps are integers, milliseconds since the Unix epoch (UTC).\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.\n\n---\n\n### Important response-shape notes\n\nThese endpoints are not served by a single serializer. Two distinct report shapes are returned depending on the endpoint, and the field-name casing differs between them:\n\n| Endpoint | Report shape | Field casing | `comments` present |\n|---|---|---|---|\n| `get_all_reports` | `ReportUpperCase` | UPPER_SNAKE_CASE | yes |\n| `get_reports_by_statuses` | `ReportUpperCase` | UPPER_SNAKE_CASE | yes |\n| `get_reports_by_incident_id` | `ReportUpperCase` | UPPER_SNAKE_CASE | yes |\n| `report/update/status` | `ReportUpperCase` | UPPER_SNAKE_CASE | yes (always `null`) |\n| `report/update/assign` | `ReportUpperCase` | UPPER_SNAKE_CASE | yes (always `null`) |\n| `get_reports_by_source_id` | `ReportRawRow` | lower_snake_case | no |\n\n`attachments` is also not uniform:\n\n- In `ReportUpperCase` it is an **array of objects** (`[]` when there are none).\n- In `ReportRawRow` it is the **raw MySQL JSON column**, returned as a JSON-encoded **string** (`\"{}\"` when there are none).\n\nSee the individual schema descriptions for details.", "contact": { "email": "docs-cortex@paloaltonetworks.com", "name": "Cortex Documentation Team", "url": "https://cortex-docs.paloaltonetworks.com/" }, "license": { "name": "Proprietary", "url": "https://www.paloaltonetworks.com/legal" } }, "servers": [ { "url": "https://api-yourfqdn", "description": "" } ], "security": [ { "Authorization": [], "x-xdr-auth-id": [] } ], "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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "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" }, "examples": { "Comment only": { "value": { "xsoar_source_id": "777771", "comment_text": "Investigation completed. No malicious activity found.", "comment_created_by": "analyst@company.com" } }, "Comment with attachment": { "value": { "xsoar_source_id": "777771", "comment_text": "Investigation completed. Report attached.", "comment_created_by": "analyst@company.com", "path_to_file": "comment/investigation-report-1234567890.pdf", "extract_zip_file": "false" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCommentResponse" }, "examples": { "Example 1": { "value": { "reply": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Comments" ] } }, "/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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "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" }, "examples": { "Get comments by report ID": { "value": { "xsoar_source_id": "777772" } }, "Get comments by time range": { "value": { "start_time": 1764512583000, "end_time": 1764517583000 } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCommentsResponse" }, "examples": { "Example 1": { "value": { "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" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Comments" ] } }, "/public_api/v1/mth/child/report/update/status": { "post": { "summary": "Update report status", "operationId": "postUpdateReportStatus", "description": "Updates the status of an MTH/MDR report.\n\n**Validation rules:**\n- `xsoar_source_id` is required. It accepts a string or an array of strings; when an array is supplied only the **first element** is used and the rest are silently ignored.\n- `report_status` is required and must be one of the supported **display** values: `New`, `In Progress`, `On Hold`, `Resolved False Positive`, `Resolved True Positive`, `Resolved Other`, `Resolved Security Testing`. The value is converted to its internal name before being stored.\n- If the report cannot be found, a generic error response is returned.\n\n**Response notes:**\n- Returns the updated report in the **UPPER_SNAKE_CASE** shape (`ReportUpperCase`).\n- `COMMENTS` is always `null` on this response — this endpoint reloads the report without its joined comments. Use `get_all_reports`, `get_reports_by_statuses`, or `get_reports_by_incident_id` to retrieve comments.\n- `ATTACHMENTS` is `null` on this response for the same reason.\n- `REPORT_STATUS` is the internal name (for example `IN_PROGRESS`), not the display value that was sent in the request.\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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "description": "Request body for updating the status of an MTH/MDR report.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportStatusRequestData" }, "examples": { "Example 1": { "value": { "xsoar_source_id": "777776", "report_status": "In Progress" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleReportResponse" }, "examples": { "Example 1": { "value": { "reply": { "XSOAR_SOURCE_ID": "777771", "NAME": "Updated Report 5", "DESCRIPTION": "Updated description", "CREATED_BY": "Unit42 Threat Hunting", "INSERT_TIME": 1763468832000, "UPDATE_TIME": 1765983782000, "ATTACHMENTS": null, "INCIDENT_ID": 1, "REPORT_TYPE": "Threat Report Update", "SEVERITY": "SEV_040_HIGH", "COMMENTS": null, "CLASSIFICATION": "MTH", "ASSIGNED_USER": "iavron@example.com", "ASSIGNED_USER_PRETTY": "iavron iavron", "REPORT_STATUS": "IN_PROGRESS" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Status" ] } }, "/public_api/v1/mth/child/report/update/assign": { "post": { "summary": "Update report assignment", "operationId": "postUpdateReportAssignment", "description": "Assigns a user to an MTH/MDR report, or clears the current assignment.\n\n**Validation rules:**\n- `xsoar_source_id` is required. It accepts a string or an array of strings; when an array is supplied only the **first element** is used and the rest are silently ignored.\n- `user` is optional. When supplied it is validated against the tenant's user list; an unknown value fails the request. When omitted or `null`, the assignment is **cleared** and `username` is forced to `null` regardless of what was sent.\n- `username` is a free-text display name and is **not** validated.\n- If the report cannot be found, a generic error response is returned.\n\n**Response notes:**\n- Returns the updated report in the **UPPER_SNAKE_CASE** shape (`ReportUpperCase`).\n- `COMMENTS` and `ATTACHMENTS` are always `null` on this response — this endpoint reloads the report without its joined comments or parsed attachment list.\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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "description": "Request body for updating the assignment of an MTH/MDR report.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportAssignUserRequestData" }, "examples": { "Assign a user": { "value": { "xsoar_source_id": "777774", "user": "analyst@company.com", "username": "Motti Analysto" } }, "Clear the assignment": { "value": { "xsoar_source_id": "777774", "user": null } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleReportResponse" }, "examples": { "Example 1": { "value": { "reply": { "XSOAR_SOURCE_ID": "777771", "NAME": "Updated Report 5", "DESCRIPTION": "Updated description", "CREATED_BY": "Unit42 Threat Hunting", "INSERT_TIME": 1763468832000, "UPDATE_TIME": 1765983782000, "ATTACHMENTS": null, "INCIDENT_ID": 1, "REPORT_TYPE": "Threat Report Update", "SEVERITY": "SEV_040_HIGH", "COMMENTS": null, "CLASSIFICATION": "MTH", "ASSIGNED_USER": "analyst@company.com", "ASSIGNED_USER_PRETTY": "Motti Analysto", "REPORT_STATUS": "ON_HOLD" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Assignment" ] } }, "/public_api/v1/mth/child/get_reports_by_source_id": { "post": { "summary": "Get reports by source ID", "operationId": "postGetReportsBySourceId", "description": "Retrieves one or more MTH/MDR reports by their `xsoar_source_id` values.\n\n**Validation rules:**\n- `xsoar_source_ids` is required and must be a non-empty string or a non-empty array of non-empty strings.\n\n**Response notes — this endpoint differs from all the others:**\n- Rows are returned **exactly as stored in MySQL**, so field names are **lower_snake_case** (`xsoar_source_id`, `incident_id`, ...), unlike every other reports endpoint which returns UPPER_SNAKE_CASE.\n- `attachments` is the **raw JSON column returned as a JSON-encoded string** (for example `\"{}\"` or `\"{\\\"update_report/...\\\": {...}}\"`), not a parsed array.\n- There is **no `comments` field** on this response; comments are not joined here.\n- `created_by` **is** included (it is absent from no shape, but note it is present here as a raw column).\n- The response is wrapped in `reply.status` / `reply.data`.\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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "description": "Request body for retrieving MTH/MDR reports by source ID.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportsBySourceIdRequestData" }, "examples": { "Single source ID": { "value": { "xsoar_source_ids": "777771" } }, "Multiple source IDs": { "value": { "xsoar_source_ids": [ "777771", "777772" ] } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportsBySourceIdResponse" }, "examples": { "Example 1": { "value": { "reply": { "status": true, "data": [ { "xsoar_source_id": "777771", "report_type": "Threat Report Update", "insert_time": 1763468832000, "update_time": 1765983782000, "name": "Updated Report 5", "description": "Updated description", "created_by": "Unit42 Threat Hunting", "incident_id": 1, "severity": "SEV_040_HIGH", "attachments": "{\"update_report/1764864986901--f2ada4b9-d7f2-43cb-978c-91cc2eb4c97d\": {\"attachment_name\": \"\", \"attachment_size\": 0}}", "classification": "MTH", "assigned_user": "iavron@example.com", "assigned_user_pretty": "iavron iavron", "report_status": "ON_HOLD" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Reports" ] } }, "/public_api/v1/mth/child/get_reports_by_incident_id": { "post": { "summary": "Get reports by incident ID", "operationId": "postGetReportsByIncidentId", "description": "Retrieves MTH/MDR reports associated with one or more incident IDs.\n\n**Validation rules:**\n- `incident_ids` is required and must be a non-empty string or a non-empty array of non-empty **strings**. Numeric JSON values are rejected by input validation even though the underlying column is an integer — send IDs as strings.\n\n**Response notes:**\n- `reply` is a **bare array** of reports. Unlike `get_all_reports` and `get_reports_by_statuses`, there is **no `DATA`/`COUNT` wrapper**, and unlike `get_reports_by_source_id` there is no `status`/`data` wrapper.\n- Reports use the **UPPER_SNAKE_CASE** shape (`ReportUpperCase`) and include the `COMMENTS` array and the parsed `ATTACHMENTS` array.\n- MTH reports typically have no incident association, so this endpoint mostly returns MDR reports.\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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "description": "Request body for retrieving MTH/MDR reports by incident ID.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportsByIncidentIdRequestData" }, "examples": { "Single incident ID": { "value": { "incident_ids": "1" } }, "Multiple incident IDs": { "value": { "incident_ids": [ "1", "2" ] } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportsByIncidentIdResponse" }, "examples": { "Example 1": { "value": { "reply": [ { "XSOAR_SOURCE_ID": "777771", "NAME": "Updated Report 5", "DESCRIPTION": "Updated description", "CREATED_BY": "Unit42 MDR", "INSERT_TIME": 1763468832000, "UPDATE_TIME": 1765983782000, "ATTACHMENTS": [], "INCIDENT_ID": 1, "REPORT_TYPE": "Threat Report Update", "SEVERITY": "SEV_040_HIGH", "COMMENTS": [], "CLASSIFICATION": "Unit 42 MDR", "ASSIGNED_USER": "iavron@example.com", "ASSIGNED_USER_PRETTY": "iavron iavron", "REPORT_STATUS": "ON_HOLD" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Reports" ] } }, "/public_api/v1/mth/child/get_all_reports": { "post": { "summary": "Get all MTH/MDR reports", "operationId": "postGetAllReports", "description": "Retrieves all MTH/MDR reports for the calling child tenant.\n\nThis endpoint takes no request parameters; any supplied body is ignored. Send `{}`.\n\n**Response notes:**\n- Reports use the **UPPER_SNAKE_CASE** shape (`ReportUpperCase`) and include the joined `COMMENTS` array and the parsed `ATTACHMENTS` array.\n- `COUNT` is derived from the internal `FILTER_COUNT` (number of reports matching the query). The internal `TOTAL_COUNT` field is stripped from the response.\n- No paging is applied, so the full report set for the tenant is returned in one response.\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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "description": "Empty request body. No parameters are required; any supplied fields are ignored.", "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Empty request body. No parameters are required." }, "examples": { "Example 1": { "value": {} } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllReportsResponse" }, "examples": { "Example 1": { "value": { "reply": { "DATA": [ { "XSOAR_SOURCE_ID": "777771", "NAME": "Updated Report 5", "DESCRIPTION": "Updated description", "CREATED_BY": "Unit42 Threat Hunting", "INSERT_TIME": 1763468832000, "UPDATE_TIME": 1765983782000, "ATTACHMENTS": [ { "ATTACHMENT_PATH": "update_report/1764864986901--f2ada4b9-d7f2-43cb-978c-91cc2eb4c97d", "ATTACHMENT_SIZE": 0, "ATTACHMENT_NAME": "" } ], "INCIDENT_ID": 1, "REPORT_TYPE": "Threat Report Update", "SEVERITY": "SEV_040_HIGH", "COMMENTS": [ { "COMMENT_ID": 21, "COMMENT_CREATED_BY": "Unit 42 Managed Services", "COMMENT_TEXT": "Hunter follow-up", "COMMENT_INSERT_TIME": 1763468843000, "COMMENT_UPDATE_TIME": null, "COMMENT_USERNAME": "analyst@company.com", "COMMENT_ATTACHMENTS": [], "COMMENT_IS_HUNTER": true } ], "CLASSIFICATION": "MTH", "ASSIGNED_USER": "iavron@example.com", "ASSIGNED_USER_PRETTY": "iavron iavron", "REPORT_STATUS": "ON_HOLD" }, { "XSOAR_SOURCE_ID": "777772", "NAME": "Royi test", "DESCRIPTION": "Royi", "CREATED_BY": "Unit42 Threat Hunting", "INSERT_TIME": 1763468615000, "UPDATE_TIME": 1763468623000, "ATTACHMENTS": [ { "ATTACHMENT_PATH": "update_report/1763468621971-sample.pdf-9b2feb72-0835-4ccf-b49c-e192550bf85f", "ATTACHMENT_SIZE": 55483, "ATTACHMENT_NAME": "sample.pdf" } ], "INCIDENT_ID": null, "REPORT_TYPE": "Monthly Status Report", "SEVERITY": "SEV_020_LOW", "COMMENTS": [], "CLASSIFICATION": "MTH", "ASSIGNED_USER": null, "ASSIGNED_USER_PRETTY": null, "REPORT_STATUS": "NEW" } ], "COUNT": 2 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Reports" ] } }, "/public_api/v1/mth/child/get_reports_by_statuses": { "post": { "summary": "Get reports by statuses", "operationId": "postGetReportsByStatuses", "description": "Retrieves MTH/MDR reports filtered by one or more status values.\n\n**Validation rules:**\n- `report_statuses` is required and must be a non-empty **array** of strings. A bare string is rejected.\n- Each entry must be one of the supported **display** values: `New`, `In Progress`, `On Hold`, `Resolved False Positive`, `Resolved True Positive`, `Resolved Other`, `Resolved Security Testing`. There is no single `Resolved` value — the four resolved outcomes are distinct.\n- Invalid values fail the request with a message listing the supported statuses.\n\n**Response notes:**\n- Identical shape to `get_all_reports`: `reply.DATA` (array of `ReportUpperCase`) plus `reply.COUNT`.\n- `REPORT_STATUS` in the response is the internal name (for example `RESOLVED_FP`), not the display value used in the request.\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", "example": "YOUR_API_KEY_HERE" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "description": "Request body for retrieving MTH/MDR reports by statuses.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportsByStatusesRequestData" }, "examples": { "Filter by single status": { "value": { "report_statuses": [ "New" ] } }, "Filter by multiple statuses": { "value": { "report_statuses": [ "New", "In Progress", "On Hold" ] } }, "Filter by resolved outcomes": { "value": { "report_statuses": [ "Resolved True Positive", "Resolved False Positive", "Resolved Other", "Resolved Security Testing" ] } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllReportsResponse" }, "examples": { "Example 1": { "value": { "reply": { "DATA": [ { "XSOAR_SOURCE_ID": "777771", "NAME": "Updated Report 5", "DESCRIPTION": "Updated description", "CREATED_BY": "Unit42 Threat Hunting", "INSERT_TIME": 1763468832000, "UPDATE_TIME": 1765983782000, "ATTACHMENTS": [], "INCIDENT_ID": 1, "REPORT_TYPE": "Threat Report Update", "SEVERITY": "SEV_040_HIGH", "COMMENTS": [], "CLASSIFICATION": "MTH", "ASSIGNED_USER": "iavron@example.com", "ASSIGNED_USER_PRETTY": "iavron iavron", "REPORT_STATUS": "IN_PROGRESS" } ], "COUNT": 1 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "Reports" ] } } }, "tags": [ { "name": "Assignment", "description": "APIs for managing report assignments" }, { "name": "Comments", "description": "APIs for managing report comments" }, { "name": "Reports", "description": "APIs for retrieving MTH/MDR reports" }, { "name": "Status", "description": "APIs for updating report status" } ], "components": { "securitySchemes": { "Authorization": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "API Key for authentication" }, "x-xdr-auth-id": { "type": "apiKey", "name": "x-xdr-auth-id", "in": "header", "description": "API Key ID for authentication" } }, "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" } } } } }, "schemas": { "ReportStatusDisplay": { "type": "string", "description": "Report status, expressed as its display value. Used in request payloads.", "enum": [ "New", "In Progress", "On Hold", "Resolved False Positive", "Resolved True Positive", "Resolved Other", "Resolved Security Testing" ] }, "ReportStatusInternal": { "type": "string", "description": "Report status, expressed as its internal name. Always used in responses.", "enum": [ "NEW", "IN_PROGRESS", "ON_HOLD", "RESOLVED_FP", "RESOLVED_TP", "RESOLVED_OTHER", "RESOLVED_SECURITY_TESTING" ] }, "Severity": { "type": "string", "nullable": true, "description": "Severity level of the report.", "enum": [ "SEV_010_INFO", "SEV_020_LOW", "SEV_030_MEDIUM", "SEV_040_HIGH", "SEV_050_CRITICAL", "SEV_090_UNKNOWN" ] }, "Classification": { "type": "string", "description": "Classification of the report. Note the MDR value is the literal string `Unit 42 MDR`, not `MDR`.", "enum": [ "MTH", "Unit 42 MDR" ] }, "Attachment": { "type": "object", "description": "A single parsed attachment entry. Keys are UPPER_SNAKE_CASE.", "properties": { "ATTACHMENT_PATH": { "type": "string", "description": "Storage key of the attachment inside the public API GCS bucket" }, "ATTACHMENT_SIZE": { "type": "integer", "nullable": true, "description": "Size of the attachment in bytes" }, "ATTACHMENT_NAME": { "type": "string", "nullable": true, "description": "Original file name of the attachment. May be an empty string." } } }, "EmbeddedComment": { "type": "object", "description": "A comment as embedded inside a `ReportUpperCase.COMMENTS` array. Keys are UPPER_SNAKE_CASE and the field set differs from the standalone `Comment` returned by `get_comments`.", "properties": { "COMMENT_ID": { "type": "integer", "description": "Unique identifier of the comment" }, "COMMENT_CREATED_BY": { "type": "string", "description": "Author of the comment. For hunter-authored comments this is masked to the literal `Unit 42 Managed Services` unless the caller is an MTH research user." }, "COMMENT_TEXT": { "type": "string", "nullable": true, "description": "Text content of the comment" }, "COMMENT_INSERT_TIME": { "type": "integer", "format": "int64", "description": "Creation timestamp in epoch milliseconds" }, "COMMENT_UPDATE_TIME": { "type": "integer", "format": "int64", "nullable": true, "description": "Last update timestamp in epoch milliseconds, or null if never edited" }, "COMMENT_USERNAME": { "type": "string", "nullable": true, "description": "User name of the account that created the comment" }, "COMMENT_ATTACHMENTS": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Parsed attachment metadata. Empty array when the comment has no attachments. Note these are metadata objects, not signed URLs — unlike the `get_comments` endpoint." }, "COMMENT_IS_HUNTER": { "type": "boolean", "description": "True when the comment was authored by a hunter/analyst rather than the customer" } } }, "ReportUpperCase": { "type": "object", "description": "MTH/MDR report as returned by `get_all_reports`, `get_reports_by_statuses`, `get_reports_by_incident_id`, `report/update/status`, and `report/update/assign`. All keys are UPPER_SNAKE_CASE.", "properties": { "XSOAR_SOURCE_ID": { "type": "string", "description": "Unique identifier of the report" }, "NAME": { "type": "string", "nullable": true, "description": "Name/title of the report" }, "DESCRIPTION": { "type": "string", "nullable": true, "description": "Detailed description of the report" }, "CREATED_BY": { "type": "string", "nullable": true, "description": "Author of the report. Normalized to `Unit42 Threat Hunting` or `Unit42 MDR` for Palo Alto Networks authored reports." }, "INSERT_TIME": { "type": "integer", "format": "int64", "nullable": true, "description": "Creation timestamp in epoch milliseconds" }, "UPDATE_TIME": { "type": "integer", "format": "int64", "nullable": true, "description": "Last update timestamp in epoch milliseconds" }, "ATTACHMENTS": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Parsed attachment metadata. Empty array when the report has no attachments. **Always `null`** on the `report/update/status` and `report/update/assign` responses." }, "INCIDENT_ID": { "type": "integer", "format": "int64", "nullable": true, "description": "Associated incident ID. Null for MTH reports, which are not incident-scoped." }, "REPORT_TYPE": { "type": "string", "nullable": true, "description": "Type of the report, as a display string. Examples: `Threat Report`, `Threat Report Update`, `Impact Report`, `Threat Inquiry`, `Threat Inquiry Update`, `Hunting Report`, `Emerging Threat Report`, `Active Campaigns Report`, `Baseline Hunting Report`, `Threat Profiling Report`, `Cyber Hygiene Report`, `Monthly Status Report`, `Evaluation Summary Report`, `Managed Case Report`." }, "SEVERITY": { "$ref": "#/components/schemas/Severity" }, "COMMENTS": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/EmbeddedComment" }, "description": "Comments joined onto the report. Empty array when the report has no comments. **Always `null`** on the `report/update/status` and `report/update/assign` responses." }, "CLASSIFICATION": { "$ref": "#/components/schemas/Classification" }, "ASSIGNED_USER": { "type": "string", "nullable": true, "description": "Email/identifier of the assigned user" }, "ASSIGNED_USER_PRETTY": { "type": "string", "nullable": true, "description": "Display name of the assigned user" }, "REPORT_STATUS": { "$ref": "#/components/schemas/ReportStatusInternal" } } }, "ReportRawRow": { "type": "object", "description": "MTH/MDR report as returned **only** by `get_reports_by_source_id`. This is the raw MySQL row: keys are lower_snake_case, `attachments` is a JSON-encoded string, and there is no `comments` field.", "properties": { "xsoar_source_id": { "type": "string", "description": "Unique identifier of the report" }, "report_type": { "type": "string", "nullable": true, "description": "Type of the report" }, "insert_time": { "type": "integer", "format": "int64", "nullable": true, "description": "Creation timestamp in epoch milliseconds" }, "update_time": { "type": "integer", "format": "int64", "nullable": true, "description": "Last update timestamp in epoch milliseconds" }, "name": { "type": "string", "nullable": true, "description": "Name/title of the report" }, "description": { "type": "string", "nullable": true, "description": "Detailed description of the report" }, "created_by": { "type": "string", "nullable": true, "description": "Author of the report" }, "incident_id": { "type": "integer", "format": "int64", "nullable": true, "description": "Associated incident ID" }, "severity": { "$ref": "#/components/schemas/Severity" }, "attachments": { "type": "string", "nullable": true, "description": "Raw MySQL JSON column, returned as a **JSON-encoded string**. `\"{}\"` when there are no attachments. Each key is the storage path and each value is an object with `attachment_name` and `attachment_size` (lower_snake_case)." }, "classification": { "$ref": "#/components/schemas/Classification" }, "assigned_user": { "type": "string", "nullable": true, "description": "Email/identifier of the assigned user" }, "assigned_user_pretty": { "type": "string", "nullable": true, "description": "Display name of the assigned user" }, "report_status": { "$ref": "#/components/schemas/ReportStatusInternal" } } }, "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 epoch milliseconds" }, "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" } } }, "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" ] } } }, "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`." } } }, "UpdateReportStatusRequestData": { "type": "object", "required": [ "xsoar_source_id", "report_status" ], "properties": { "xsoar_source_id": { "description": "XSOAR source ID of the report to update. Accepts a string or an array of strings; only the first element of an array is used.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "report_status": { "$ref": "#/components/schemas/ReportStatusDisplay" } } }, "UpdateReportAssignUserRequestData": { "type": "object", "required": [ "xsoar_source_id" ], "properties": { "xsoar_source_id": { "description": "XSOAR source ID of the report to update. Accepts a string or an array of strings; only the first element of an array is used.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "user": { "type": "string", "nullable": true, "description": "Identifier (typically email) of the user to assign the report to. Validated against the tenant's users. Omit or set to `null` to clear the assignment." }, "username": { "type": "string", "nullable": true, "description": "Display name of the assignee. Free text; not validated. Forced to `null` when `user` is `null`." } } }, "GetReportsBySourceIdRequestData": { "type": "object", "required": [ "xsoar_source_ids" ], "properties": { "xsoar_source_ids": { "description": "A single XSOAR source ID or an array of XSOAR source IDs. Values must be non-empty strings.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] } } }, "GetReportsByIncidentIdRequestData": { "type": "object", "required": [ "incident_ids" ], "properties": { "incident_ids": { "description": "A single incident ID or an array of incident IDs. Values must be non-empty **strings**; numeric JSON values are rejected.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] } } }, "GetReportsByStatusesRequestData": { "type": "object", "required": [ "report_statuses" ], "properties": { "report_statuses": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ReportStatusDisplay" }, "description": "Non-empty array of report statuses to filter by. Must be an array; a bare string is rejected." } } }, "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`." } } }, "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" } } } } }, "SingleReportResponse": { "type": "object", "description": "Response for the status-update and assignment-update endpoints. `reply.COMMENTS` and `reply.ATTACHMENTS` are always `null` here.", "properties": { "reply": { "$ref": "#/components/schemas/ReportUpperCase" } } }, "GetReportsBySourceIdResponse": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Operation success status" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRawRow" }, "description": "Array of raw report rows matching the requested source IDs. Note the lower_snake_case field names and the string-encoded `attachments`." } } } } }, "GetReportsByIncidentIdResponse": { "type": "object", "properties": { "reply": { "type": "array", "items": { "$ref": "#/components/schemas/ReportUpperCase" }, "description": "Bare array of report objects matching the requested incident IDs. There is no `DATA`/`COUNT` wrapper on this endpoint." } } }, "GetAllReportsResponse": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "DATA": { "type": "array", "items": { "$ref": "#/components/schemas/ReportUpperCase" }, "description": "Array of report objects matching the query" }, "COUNT": { "type": "integer", "description": "Number of reports matching the applied filters" } } } } }, "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." } } } } } } } }