> 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/xdr-5-api/managed-services/assignment.md). # Assignment APIs for managing report assignments ## Update report assignment > Assigns a user to an MTH/MDR report, or clears the current assignment.\ > \ > \*\*Validation rules:\*\*\ > \- \`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.\ > \- \`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.\ > \- \`username\` is a free-text display name and is \*\*not\*\* validated.\ > \- If the report cannot be found, a generic error response is returned.\ > \ > \*\*Response notes:\*\*\ > \- Returns the updated report in the \*\*UPPER\_SNAKE\_CASE\*\* shape (\`ReportUpperCase\`).\ > \- \`COMMENTS\` and \`ATTACHMENTS\` are always \`null\` on this response — this endpoint reloads the report without its joined comments or parsed attachment list.\ > \ > \*\*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":"Assignment","description":"APIs for managing report assignments"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","name":"Authorization","in":"header","description":"API Key for authentication"}},"schemas":{"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`."}}},"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"}}},"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"}}},"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."}}},"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"]},"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"}}},"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"]},"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"]},"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/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"},"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 updating the assignment of an MTH/MDR report.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateReportAssignUserRequestData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleReportResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}},"tags":["Assignment"]}}}} ``` --- # 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/xdr-5-api/managed-services/assignment.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.