> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/reference/api-v1/issues.md). # Issues The Issues API provides programmatic access to security [issues](https://docs.material.security/getting-started/fundamentals/investigate) detected by Material. Query and paginate issues, filter by status, drill down into a specific issue for details including severity and classification, and retrieve the associated email messages along with link and attachment counts. These endpoints make up the Issues API: * [**List Issues**](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues) (`GET /api/v1/issues`): filter and retrieve a paginated list of issues * [**Get Issue**](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id) (`GET /api/v1/issues/{id}`): retrieve a single issue by its encoded ID * [**List Issue Messages**](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id-messages) (`GET /api/v1/issues/{id}/messages`): retrieve the email messages associated with a specific issue * [**Update Issue**](https://docs.material.security/reference/api-v1/issues#patch-api-v1-issues-id) (`PATCH /api/v1/issues/{id}`): update the status, classification, assignee, or remediation actions on an existing issue **Response Structure** Most Issues API responses (except **Update Issue**) follow a consistent two-part structure: * **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination. * **`items`**: an array containing the actual results, such as issues or messages. This pattern applies to all paginated endpoints, as well as to nested collections within a single issue response, for example, `comments`, `accounts`, `messages`, and `files` each return their own `meta` and `items` when requested via the `include` parameter. **The `include` Parameter** By default, issue responses return a core set of fields: ID, name, status, severity, classification, detection rule, primary entity, and key lifecycle timestamps. To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter. Supported values are `comments`, `accounts`, `messages`, and `files`. Pass multiple values as a comma-separated list (e.g. `include=comments,accounts`). **Want a walkthrough?** Review [Hello World](https://docs.material.security/reference/api-v1/hello-world). **Pagination and Rate Limiting** * Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request. * The `limit` parameter controls page size on all paginated endpoints. * Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set. * When `hasMore` is false and `nextCursor` is null, you've reached the last page. ## List Issues > Retrieves a paginated list of security issues detected by Material. Filter by status to surface open or in-progress threats, and use the include parameter to pull in related data such as comments, accounts, and messages in a single request. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Issues","description":"\nThe Issues API provides programmatic access to security [issues](https://docs.material.security/getting-started/fundamentals/investigate) detected by Material. Query and paginate issues, filter by status, drill down into a specific issue for details including severity and classification, and retrieve the associated email messages along with link and attachment counts.\n\nThese endpoints make up the Issues API:\n\n* **[List Issues](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues)** (`GET /api/v1/issues`): filter and retrieve a paginated list of issues \n* **[Get Issue](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id)** (`GET /api/v1/issues/{id}`): retrieve a single issue by its encoded ID \n* **[List Issue Messages](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id-messages)** (`GET /api/v1/issues/{id}/messages`): retrieve the email messages associated with a specific issue\n* **[Update Issue](https://docs.material.security/reference/api-v1/issues#patch-api-v1-issues-id)** (`PATCH /api/v1/issues/{id}`): update the status, classification, assignee, or remediation actions on an existing issue\n\n**Response Structure**\n\nMost Issues API responses (except **Update Issue**) follow a consistent two-part structure:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination. \n* **`items`**: an array containing the actual results, such as issues or messages.\n\nThis pattern applies to all paginated endpoints, as well as to nested collections within a single issue response, for example, `comments`, `accounts`, `messages`, and `files` each return their own `meta` and `items` when requested via the `include` parameter.\n\n**The `include` Parameter**\n\nBy default, issue responses return a core set of fields: ID, name, status, severity, classification, detection rule, primary entity, and key lifecycle timestamps. To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter. Supported values are `comments`, `accounts`, `messages`, and `files`. Pass multiple values as a comma-separated list (e.g. `include=comments,accounts`).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request. \n* The `limit` parameter controls page size on all paginated endpoints. \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set. \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APIIssueCollection":{"title":"APIIssueCollection","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIIssue"}}},"required":["meta","items"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APIIssue":{"title":"APIIssue","description":"A security issue representing a detected threat or anomaly. In app, view these under *Issues*.","type":"object","properties":{"id":{"description":"The encoded issue ID. Format: `iss.1.`.","type":"string"},"name":{"description":"Issue display name derived from the detection rule that triggered it","type":"string"},"status":{"description":"Current [issue status](https://docs.material.security/getting-started/fundamentals/investigate#status): `open`, `in_progress`, `resolved`, `ignored`, or `snoozed`.","type":"string","enum":["open","in_progress","resolved","ignored","snoozed"]},"severity":{"description":"Issue [severity level](https://docs.material.security/getting-started/fundamentals/detect/detection-severity-framework): `01_info`, `02_low`, `03_medium`, `04_high`, or `05_critical`.","type":"string","enum":["01_info","02_low","03_medium","04_high","05_critical"]},"classification":{"description":"Issue classification (safe, malicious, spam, unknown), or null if not yet classified.","anyOf":[{"type":"string","enum":["safe","malicious","spam","unknown"]},{"type":"null"}]},"analysis":{"title":"APIAnalysis","description":"The analysis results for this issue, including insight tags that describe the threat category and techniques.","$ref":"#/components/schemas/APIAnalysis"},"primaryEntity":{"title":"APIPrimaryEntity","description":"The primary entity associated with this issue. Exactly one of the optional fields will be populated based on `type`.","$ref":"#/components/schemas/APIPrimaryEntity"},"keyEvents":{"title":"APIKeyEvents","description":"The key lifecycle timestamps for this issue, including when it was created, opened, and last updated.","$ref":"#/components/schemas/APIKeyEvents"},"tenantId":{"description":"The encoded tenant ID. Format: `tnt.1.`. Null if no tenant is associated.","anyOf":[{"type":"string"},{"type":"null"}]},"detection":{"title":"APIDetection","description":"The detection rule that triggered this issue.","$ref":"#/components/schemas/APIDetection"},"assigneeId":{"description":"The encoded account ID of the assignee. Format: `acct.1.`. Null if the issue is unassigned.","anyOf":[{"type":"string"},{"type":"null"}]},"ignoreReason":{"description":"Why the status was set to \"ignored\", or null if status is not \"ignored\".","anyOf":[{"type":"string","enum":["false_positive","exception","automatic"]},{"type":"null"}]},"snoozedUntil":{"description":"When the snoozed issue will reopen. Null if the issue is not snoozed.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"supportedRemediations":{"description":"The types of remediation action that can be put in the `remediation` list.","type":"array","items":{"type":"string","enum":["email_threat"]}},"remediation":{"description":"The remediation to apply to the issue. The order does not matter. Each must have a `type` from `supportedRemediations`.","type":"array","items":{"description":"Remediation actions that can be applied to an issue, when the type is in `issue.supportedRemediations`.","oneOf":[{"description":"Remediation actions available for issues with `detection.type=\"email_threat\"`.","oneOf":[{"description":"Remove the message from the mailbox, and any calendar events it created.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"delete"}},"required":["type","action"]},{"description":"Remove any calendar events the message created, but leave the message in the mailbox.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"deleteCalendarEvents"}},"required":["type","action"]},{"description":"Move the message into the spam folder.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"moveToSpam"}},"required":["type","action"]},{"description":"Add a warning banner to the top of the message.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"addBanner"},"message":{"description":"The message to put in the banner. If unset, a default is used.","type":"string"}},"required":["type","action"]},{"description":"Redirect links and attachments to a warning page.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"redirectLinksAndAttachments"},"mode":{"description":"If \"block\", the content is inaccessible. If \"speedbump\", the user may choose whether to continue to the content after reading the warning.","type":"string","enum":["block","speedbump"]}},"required":["type","action","mode"]},{"description":"Send a response to users that report the message as suspicious.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"respondToReporters"},"message":{"description":"The message to send to reporting users.","type":"string"},"sendToPreviousReporters":{"description":"If false / missing, only send to new reporters going forward. If true, also immediately send to all previous reporters.","type":"boolean"}},"required":["type","action"]}],"type":"object"}],"type":"object"}},"comments":{"description":"Issue comments. Populated when `include=comments`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIIssueComment"}}},"required":["meta","items"]},"accounts":{"description":"The accounts associated with this issue. Populated only when `include=accounts` is specified.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIAccountSummary"}}},"required":["meta","items"]},"messages":{"description":"Related messages. Populated when `include=messages`.","type":"object","properties":{"meta":{"type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]},"numLinks":{"description":"Number of links found in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"numAttachments":{"description":"Number of file attachments in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["numLinks","numAttachments"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIMessageItem"}}},"required":["meta","items"]},"files":{"description":"Related files. Populated when `include=files`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIFileSummary"}}},"required":["meta","items"]}},"required":["id","name","status","severity","classification","analysis","primaryEntity","keyEvents","tenantId","detection","assigneeId","ignoreReason","snoozedUntil","supportedRemediations","remediation"]},"APIAnalysis":{"title":"APIAnalysis","type":"object","properties":{"insights":{"description":"Analysis insight tags. Prefixed by type: `category.*`, `subcategory.*`, `ttp.*`. Example: `category.credential_phishing`, `ttp.link_based`.","type":"array","items":{"type":"string"}}},"required":["insights"]},"APIPrimaryEntity":{"title":"APIPrimaryEntity","type":"object","properties":{"type":{"description":"The entity type. Determines which optional field is populated.","type":"string","enum":["tenant","account","group","file","message","app"]},"account":{"description":"Present when `type` is `account`","$ref":"#/components/schemas/APIAccountEntity"},"message":{"description":"Present when `type` is `message`","$ref":"#/components/schemas/APIMessageEntity"},"file":{"description":"Present when `type` is `file`","$ref":"#/components/schemas/APIFileEntity"},"tenant":{"description":"Present when `type` is `tenant`","$ref":"#/components/schemas/APITenantEntity"},"group":{"description":"Present when `type` is `group`","$ref":"#/components/schemas/APIGroupEntity"},"app":{"description":"Present when `type` is `app`","$ref":"#/components/schemas/APIAppEntity"}},"required":["type"]},"APIAccountEntity":{"title":"APIAccountEntity","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"email":{"description":"The Email address of the account. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"description":"The display name of the account holder. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","email","displayName"]},"APIMessageEntity":{"title":"APIMessageEntity","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"date":{"description":"Message date in ISO 8601 format","type":"string","format":"date-time"},"from":{"description":"Sender email address","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","date","from"]},"APIFileEntity":{"title":"APIFileEntity","type":"object","properties":{"id":{"description":"The encoded file ID. Format: `file.1.`.","type":"string"},"name":{"description":"File name","anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"description":"MIME type (e.g. `application/pdf`)","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","mimeType"]},"APITenantEntity":{"title":"APITenantEntity","type":"object","properties":{"csp":{"description":"Cloud service provider (`microsoft` or `google`)","anyOf":[{"type":"string","enum":["microsoft","google"]},{"type":"null"}]}},"required":["csp"]},"APIGroupEntity":{"title":"APIGroupEntity","type":"object","properties":{"name":{"description":"Group name","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"APIAppEntity":{"title":"APIAppEntity","type":"object","properties":{"appType":{"description":"Application type","type":"string","enum":["oauth-token-grant","email-app"]}},"required":["appType"]},"APIKeyEvents":{"title":"APIKeyEvents","type":"object","properties":{"created":{"description":"When the issue was first created","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]},"opened":{"description":"When the issue was last opened","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]},"statusChanged":{"description":"When the issue status last changed","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]}},"required":["created","opened","statusChanged"]},"APIDetection":{"title":"APIDetection","type":"object","properties":{"id":{"description":"The encoded detection ID. Format: `det.1.`.","type":"string"},"name":{"description":"The display name of the detection rule. Null if the rule is unnamed.","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"description":"Detection type: `vulnerability`, `threat`, or `email_threat`.","type":"string","enum":["vulnerability","threat","email_threat"]}},"required":["id","name","type"]},"APIIssueComment":{"title":"APIIssueComment","type":"object","properties":{"comment":{"description":"Comment text","type":"string"},"author":{"description":"Author name or email","type":"string"},"timestamp":{"description":"When the comment was posted","type":"string","format":"date-time"}},"required":["comment","author","timestamp"]},"APIAccountSummary":{"title":"APIAccountSummary","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"email":{"description":"Email address (included with `include=accounts.email`)","type":"string"},"displayName":{"description":"Display name (included with `include=accounts.displayName`)","type":"string"}},"required":["id"]},"APIMessageItem":{"title":"APIMessageItem","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"headers":{"$ref":"#/components/schemas/APIMessageItemHeaders"}},"required":["id"]},"APIMessageItemHeaders":{"title":"APIMessageItemHeaders","type":"object","properties":{"date":{"description":"The date the message was sent, in ISO 8601 format.","type":"string","format":"date-time"},"from":{"description":"The sender address of the message. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["date","from"]},"APIFileSummary":{"title":"APIFileSummary","type":"object","properties":{"id":{"description":"The encoded file ID. Format: `file.1.`.","type":"string"},"name":{"description":"File name (included with `include=files.name`)","type":"string"},"mimeType":{"description":"MIME type (included with `include=files.mimeType`)","type":"string"}},"required":["id"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/issues":{"get":{"operationId":"listIssues","summary":"List Issues","description":"Retrieves a paginated list of security issues detected by Material. Filter by status to surface open or in-progress threats, and use the include parameter to pull in related data such as comments, accounts, and messages in a single request.","tags":["Issues"],"parameters":[{"in":"query","name":"include","schema":{"description":"A comma-separated list of additional fields to include in the response. Valid values: `comments`, `accounts`, `messages`, `files`. Use dot notation to select sub-fields (for example, `accounts.email`). Use `*` to include all available fields.","type":"string"},"description":"A comma-separated list of additional fields to include in the response. Valid values: `comments`, `accounts`, `messages`, `files`. Use dot notation to select sub-fields (for example, `accounts.email`). Use `*` to include all available fields."},{"in":"query","name":"status","schema":{"description":"[Issue statuses](https://docs.material.security/getting-started/fundamentals/investigate#status) to filter the response by, specified as a comma-separated list.","type":"string"},"description":"[Issue statuses](https://docs.material.security/getting-started/fundamentals/investigate#status) to filter the response by, specified as a comma-separated list."},{"in":"query","name":"severity","schema":{"description":"Comma-separated list of severity levels to filter by.","type":"string"},"description":"Comma-separated list of severity levels to filter by."},{"in":"query","name":"primaryEntity.type","schema":{"description":"Comma-separated list of primary entity types to filter by.","type":"string"},"description":"Comma-separated list of primary entity types to filter by."},{"in":"query","name":"detection.type","schema":{"description":"Comma-separated list of detection types to filter by.","type":"string"},"description":"Comma-separated list of detection types to filter by."},{"in":"query","name":"detection.id","schema":{"description":"Comma-separated list of encoded detection IDs (`det.1.`) to filter by.","type":"string"},"description":"Comma-separated list of encoded detection IDs (`det.1.`) to filter by."},{"in":"query","name":"sort","schema":{"description":"Comma-separated list of fields to sort by, applied in the order given, with a stable secondary sort by issue ID. Each field may be suffixed with `:asc` or `:desc` to specify direction; a bare field uses the natural default direction for that field — descending for `severity` and any `keyEvents.*` timestamp. Valid fields: `severity`, `keyEvents.created`, `keyEvents.statusChanged`. Default when omitted: `severity,keyEvents.statusChanged` (both descending).","type":"string"},"description":"Comma-separated list of fields to sort by, applied in the order given, with a stable secondary sort by issue ID. Each field may be suffixed with `:asc` or `:desc` to specify direction; a bare field uses the natural default direction for that field — descending for `severity` and any `keyEvents.*` timestamp. Valid fields: `severity`, `keyEvents.created`, `keyEvents.statusChanged`. Default when omitted: `severity,keyEvents.statusChanged` (both descending)."},{"in":"query","name":"cursor","schema":{"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.","type":"string"},"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results."},{"in":"query","name":"limit","schema":{"description":"The maximum number of items to return per page.","type":"integer"},"description":"The maximum number of items to return per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIIssueCollection"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Get Issue > Retrieves the full details of a single issue by its encoded ID, including severity, classification, primary entity, detection rule, and key lifecycle timestamps. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Issues","description":"\nThe Issues API provides programmatic access to security [issues](https://docs.material.security/getting-started/fundamentals/investigate) detected by Material. Query and paginate issues, filter by status, drill down into a specific issue for details including severity and classification, and retrieve the associated email messages along with link and attachment counts.\n\nThese endpoints make up the Issues API:\n\n* **[List Issues](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues)** (`GET /api/v1/issues`): filter and retrieve a paginated list of issues \n* **[Get Issue](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id)** (`GET /api/v1/issues/{id}`): retrieve a single issue by its encoded ID \n* **[List Issue Messages](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id-messages)** (`GET /api/v1/issues/{id}/messages`): retrieve the email messages associated with a specific issue\n* **[Update Issue](https://docs.material.security/reference/api-v1/issues#patch-api-v1-issues-id)** (`PATCH /api/v1/issues/{id}`): update the status, classification, assignee, or remediation actions on an existing issue\n\n**Response Structure**\n\nMost Issues API responses (except **Update Issue**) follow a consistent two-part structure:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination. \n* **`items`**: an array containing the actual results, such as issues or messages.\n\nThis pattern applies to all paginated endpoints, as well as to nested collections within a single issue response, for example, `comments`, `accounts`, `messages`, and `files` each return their own `meta` and `items` when requested via the `include` parameter.\n\n**The `include` Parameter**\n\nBy default, issue responses return a core set of fields: ID, name, status, severity, classification, detection rule, primary entity, and key lifecycle timestamps. To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter. Supported values are `comments`, `accounts`, `messages`, and `files`. Pass multiple values as a comma-separated list (e.g. `include=comments,accounts`).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request. \n* The `limit` parameter controls page size on all paginated endpoints. \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set. \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APIIssue":{"title":"APIIssue","description":"A security issue representing a detected threat or anomaly. In app, view these under *Issues*.","type":"object","properties":{"id":{"description":"The encoded issue ID. Format: `iss.1.`.","type":"string"},"name":{"description":"Issue display name derived from the detection rule that triggered it","type":"string"},"status":{"description":"Current [issue status](https://docs.material.security/getting-started/fundamentals/investigate#status): `open`, `in_progress`, `resolved`, `ignored`, or `snoozed`.","type":"string","enum":["open","in_progress","resolved","ignored","snoozed"]},"severity":{"description":"Issue [severity level](https://docs.material.security/getting-started/fundamentals/detect/detection-severity-framework): `01_info`, `02_low`, `03_medium`, `04_high`, or `05_critical`.","type":"string","enum":["01_info","02_low","03_medium","04_high","05_critical"]},"classification":{"description":"Issue classification (safe, malicious, spam, unknown), or null if not yet classified.","anyOf":[{"type":"string","enum":["safe","malicious","spam","unknown"]},{"type":"null"}]},"analysis":{"title":"APIAnalysis","description":"The analysis results for this issue, including insight tags that describe the threat category and techniques.","$ref":"#/components/schemas/APIAnalysis"},"primaryEntity":{"title":"APIPrimaryEntity","description":"The primary entity associated with this issue. Exactly one of the optional fields will be populated based on `type`.","$ref":"#/components/schemas/APIPrimaryEntity"},"keyEvents":{"title":"APIKeyEvents","description":"The key lifecycle timestamps for this issue, including when it was created, opened, and last updated.","$ref":"#/components/schemas/APIKeyEvents"},"tenantId":{"description":"The encoded tenant ID. Format: `tnt.1.`. Null if no tenant is associated.","anyOf":[{"type":"string"},{"type":"null"}]},"detection":{"title":"APIDetection","description":"The detection rule that triggered this issue.","$ref":"#/components/schemas/APIDetection"},"assigneeId":{"description":"The encoded account ID of the assignee. Format: `acct.1.`. Null if the issue is unassigned.","anyOf":[{"type":"string"},{"type":"null"}]},"ignoreReason":{"description":"Why the status was set to \"ignored\", or null if status is not \"ignored\".","anyOf":[{"type":"string","enum":["false_positive","exception","automatic"]},{"type":"null"}]},"snoozedUntil":{"description":"When the snoozed issue will reopen. Null if the issue is not snoozed.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"supportedRemediations":{"description":"The types of remediation action that can be put in the `remediation` list.","type":"array","items":{"type":"string","enum":["email_threat"]}},"remediation":{"description":"The remediation to apply to the issue. The order does not matter. Each must have a `type` from `supportedRemediations`.","type":"array","items":{"description":"Remediation actions that can be applied to an issue, when the type is in `issue.supportedRemediations`.","oneOf":[{"description":"Remediation actions available for issues with `detection.type=\"email_threat\"`.","oneOf":[{"description":"Remove the message from the mailbox, and any calendar events it created.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"delete"}},"required":["type","action"]},{"description":"Remove any calendar events the message created, but leave the message in the mailbox.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"deleteCalendarEvents"}},"required":["type","action"]},{"description":"Move the message into the spam folder.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"moveToSpam"}},"required":["type","action"]},{"description":"Add a warning banner to the top of the message.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"addBanner"},"message":{"description":"The message to put in the banner. If unset, a default is used.","type":"string"}},"required":["type","action"]},{"description":"Redirect links and attachments to a warning page.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"redirectLinksAndAttachments"},"mode":{"description":"If \"block\", the content is inaccessible. If \"speedbump\", the user may choose whether to continue to the content after reading the warning.","type":"string","enum":["block","speedbump"]}},"required":["type","action","mode"]},{"description":"Send a response to users that report the message as suspicious.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"respondToReporters"},"message":{"description":"The message to send to reporting users.","type":"string"},"sendToPreviousReporters":{"description":"If false / missing, only send to new reporters going forward. If true, also immediately send to all previous reporters.","type":"boolean"}},"required":["type","action"]}],"type":"object"}],"type":"object"}},"comments":{"description":"Issue comments. Populated when `include=comments`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIIssueComment"}}},"required":["meta","items"]},"accounts":{"description":"The accounts associated with this issue. Populated only when `include=accounts` is specified.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIAccountSummary"}}},"required":["meta","items"]},"messages":{"description":"Related messages. Populated when `include=messages`.","type":"object","properties":{"meta":{"type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]},"numLinks":{"description":"Number of links found in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"numAttachments":{"description":"Number of file attachments in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["numLinks","numAttachments"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIMessageItem"}}},"required":["meta","items"]},"files":{"description":"Related files. Populated when `include=files`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIFileSummary"}}},"required":["meta","items"]}},"required":["id","name","status","severity","classification","analysis","primaryEntity","keyEvents","tenantId","detection","assigneeId","ignoreReason","snoozedUntil","supportedRemediations","remediation"]},"APIAnalysis":{"title":"APIAnalysis","type":"object","properties":{"insights":{"description":"Analysis insight tags. Prefixed by type: `category.*`, `subcategory.*`, `ttp.*`. Example: `category.credential_phishing`, `ttp.link_based`.","type":"array","items":{"type":"string"}}},"required":["insights"]},"APIPrimaryEntity":{"title":"APIPrimaryEntity","type":"object","properties":{"type":{"description":"The entity type. Determines which optional field is populated.","type":"string","enum":["tenant","account","group","file","message","app"]},"account":{"description":"Present when `type` is `account`","$ref":"#/components/schemas/APIAccountEntity"},"message":{"description":"Present when `type` is `message`","$ref":"#/components/schemas/APIMessageEntity"},"file":{"description":"Present when `type` is `file`","$ref":"#/components/schemas/APIFileEntity"},"tenant":{"description":"Present when `type` is `tenant`","$ref":"#/components/schemas/APITenantEntity"},"group":{"description":"Present when `type` is `group`","$ref":"#/components/schemas/APIGroupEntity"},"app":{"description":"Present when `type` is `app`","$ref":"#/components/schemas/APIAppEntity"}},"required":["type"]},"APIAccountEntity":{"title":"APIAccountEntity","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"email":{"description":"The Email address of the account. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"description":"The display name of the account holder. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","email","displayName"]},"APIMessageEntity":{"title":"APIMessageEntity","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"date":{"description":"Message date in ISO 8601 format","type":"string","format":"date-time"},"from":{"description":"Sender email address","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","date","from"]},"APIFileEntity":{"title":"APIFileEntity","type":"object","properties":{"id":{"description":"The encoded file ID. Format: `file.1.`.","type":"string"},"name":{"description":"File name","anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"description":"MIME type (e.g. `application/pdf`)","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","mimeType"]},"APITenantEntity":{"title":"APITenantEntity","type":"object","properties":{"csp":{"description":"Cloud service provider (`microsoft` or `google`)","anyOf":[{"type":"string","enum":["microsoft","google"]},{"type":"null"}]}},"required":["csp"]},"APIGroupEntity":{"title":"APIGroupEntity","type":"object","properties":{"name":{"description":"Group name","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"APIAppEntity":{"title":"APIAppEntity","type":"object","properties":{"appType":{"description":"Application type","type":"string","enum":["oauth-token-grant","email-app"]}},"required":["appType"]},"APIKeyEvents":{"title":"APIKeyEvents","type":"object","properties":{"created":{"description":"When the issue was first created","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]},"opened":{"description":"When the issue was last opened","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]},"statusChanged":{"description":"When the issue status last changed","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]}},"required":["created","opened","statusChanged"]},"APIDetection":{"title":"APIDetection","type":"object","properties":{"id":{"description":"The encoded detection ID. Format: `det.1.`.","type":"string"},"name":{"description":"The display name of the detection rule. Null if the rule is unnamed.","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"description":"Detection type: `vulnerability`, `threat`, or `email_threat`.","type":"string","enum":["vulnerability","threat","email_threat"]}},"required":["id","name","type"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APIIssueComment":{"title":"APIIssueComment","type":"object","properties":{"comment":{"description":"Comment text","type":"string"},"author":{"description":"Author name or email","type":"string"},"timestamp":{"description":"When the comment was posted","type":"string","format":"date-time"}},"required":["comment","author","timestamp"]},"APIAccountSummary":{"title":"APIAccountSummary","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"email":{"description":"Email address (included with `include=accounts.email`)","type":"string"},"displayName":{"description":"Display name (included with `include=accounts.displayName`)","type":"string"}},"required":["id"]},"APIMessageItem":{"title":"APIMessageItem","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"headers":{"$ref":"#/components/schemas/APIMessageItemHeaders"}},"required":["id"]},"APIMessageItemHeaders":{"title":"APIMessageItemHeaders","type":"object","properties":{"date":{"description":"The date the message was sent, in ISO 8601 format.","type":"string","format":"date-time"},"from":{"description":"The sender address of the message. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["date","from"]},"APIFileSummary":{"title":"APIFileSummary","type":"object","properties":{"id":{"description":"The encoded file ID. Format: `file.1.`.","type":"string"},"name":{"description":"File name (included with `include=files.name`)","type":"string"},"mimeType":{"description":"MIME type (included with `include=files.mimeType`)","type":"string"}},"required":["id"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/issues/{id}":{"get":{"operationId":"getIssue","summary":"Get Issue","description":"Retrieves the full details of a single issue by its encoded ID, including severity, classification, primary entity, detection rule, and key lifecycle timestamps.","tags":["Issues"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the issue to retrieve. Format: `iss.1.`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the issue to retrieve. Format: `iss.1.`."},{"in":"query","name":"include","schema":{"description":"A comma-separated list of additional fields to include in the response. Valid values: `comments`, `accounts`, `messages`, `files`. Use dot notation to select sub-fields (for example, `accounts.email`). Use `*` to include all available fields.","type":"string"},"description":"A comma-separated list of additional fields to include in the response. Valid values: `comments`, `accounts`, `messages`, `files`. Use dot notation to select sub-fields (for example, `accounts.email`). Use `*` to include all available fields."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIIssue"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Update Issue > Updates the status, classification, assignee, or remediation actions on an existing issue. Only fields included in the request body are changed. Supports setting ignore reasons, snooze windows, and email threat remediation actions such as deleting messages, adding warning banners, or redirecting links and attachments. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Issues","description":"\nThe Issues API provides programmatic access to security [issues](https://docs.material.security/getting-started/fundamentals/investigate) detected by Material. Query and paginate issues, filter by status, drill down into a specific issue for details including severity and classification, and retrieve the associated email messages along with link and attachment counts.\n\nThese endpoints make up the Issues API:\n\n* **[List Issues](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues)** (`GET /api/v1/issues`): filter and retrieve a paginated list of issues \n* **[Get Issue](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id)** (`GET /api/v1/issues/{id}`): retrieve a single issue by its encoded ID \n* **[List Issue Messages](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id-messages)** (`GET /api/v1/issues/{id}/messages`): retrieve the email messages associated with a specific issue\n* **[Update Issue](https://docs.material.security/reference/api-v1/issues#patch-api-v1-issues-id)** (`PATCH /api/v1/issues/{id}`): update the status, classification, assignee, or remediation actions on an existing issue\n\n**Response Structure**\n\nMost Issues API responses (except **Update Issue**) follow a consistent two-part structure:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination. \n* **`items`**: an array containing the actual results, such as issues or messages.\n\nThis pattern applies to all paginated endpoints, as well as to nested collections within a single issue response, for example, `comments`, `accounts`, `messages`, and `files` each return their own `meta` and `items` when requested via the `include` parameter.\n\n**The `include` Parameter**\n\nBy default, issue responses return a core set of fields: ID, name, status, severity, classification, detection rule, primary entity, and key lifecycle timestamps. To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter. Supported values are `comments`, `accounts`, `messages`, and `files`. Pass multiple values as a comma-separated list (e.g. `include=comments,accounts`).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request. \n* The `limit` parameter controls page size on all paginated endpoints. \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set. \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"UpdateIssueBody":{"title":"UpdateIssueBody","description":"Fields to update on the issue. Only provided fields are changed.","type":"object","properties":{"status":{"description":"New [issue status](https://docs.material.security/getting-started/fundamentals/investigate#status): `open`, `in_progress`, `resolved`, `ignored`, or `snoozed`. To ignore or snooze, you must set `ignoreReason` or `snoozedUntil`.","type":"string","enum":["open","in_progress","resolved","ignored","snoozed"]},"classification":{"description":"New issue [classification](https://docs.material.security/getting-started/fundamentals/investigate#status): `safe`, `malicious`, `spam`, or `unknown`. When set without an explicit `remediation`, the default remediation for that classification is applied automatically.","type":"string","enum":["safe","malicious","spam","unknown"]},"assigneeId":{"description":"The encoded account ID of the new assignee. Format: `acct.1.`. Null to unassign.","anyOf":[{"type":"string"},{"type":"null"}]},"ignoreReason":{"description":"Why the status was set to \"ignored\". Setting this will also set the status to \"ignored\".","type":"string","enum":["false_positive","exception"]},"snoozedUntil":{"description":"When the snoozed issue will reopen. Setting this will also set the status to \"snoozed\".","type":"string","format":"date-time"},"remediation":{"description":"The remediation to apply to the issue. The order does not matter. Each must have a `type` from `supportedRemediations`. If conflicting actions are included, only the strictest will be kept. This replaces the list entirely, it is not merged.","type":"array","items":{"description":"Remediation actions that can be applied to an issue, when the type is in `issue.supportedRemediations`.","oneOf":[{"description":"Remediation actions available for issues with `detection.type=\"email_threat\"`.","oneOf":[{"description":"Remove the message from the mailbox, and any calendar events it created.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"delete"}},"required":["type","action"]},{"description":"Remove any calendar events the message created, but leave the message in the mailbox.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"deleteCalendarEvents"}},"required":["type","action"]},{"description":"Move the message into the spam folder.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"moveToSpam"}},"required":["type","action"]},{"description":"Add a warning banner to the top of the message.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"addBanner"},"message":{"description":"The message to put in the banner. If unset, a default is used.","type":"string"}},"required":["type","action"]},{"description":"Redirect links and attachments to a warning page.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"redirectLinksAndAttachments"},"mode":{"description":"If \"block\", the content is inaccessible. If \"speedbump\", the user may choose whether to continue to the content after reading the warning.","type":"string","enum":["block","speedbump"]}},"required":["type","action","mode"]},{"description":"Send a response to users that report the message as suspicious.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"respondToReporters"},"message":{"description":"The message to send to reporting users.","type":"string"},"sendToPreviousReporters":{"description":"If false / missing, only send to new reporters going forward. If true, also immediately send to all previous reporters.","type":"boolean"}},"required":["type","action"]}],"type":"object"}],"type":"object"}}}},"APIIssue":{"title":"APIIssue","description":"A security issue representing a detected threat or anomaly. In app, view these under *Issues*.","type":"object","properties":{"id":{"description":"The encoded issue ID. Format: `iss.1.`.","type":"string"},"name":{"description":"Issue display name derived from the detection rule that triggered it","type":"string"},"status":{"description":"Current [issue status](https://docs.material.security/getting-started/fundamentals/investigate#status): `open`, `in_progress`, `resolved`, `ignored`, or `snoozed`.","type":"string","enum":["open","in_progress","resolved","ignored","snoozed"]},"severity":{"description":"Issue [severity level](https://docs.material.security/getting-started/fundamentals/detect/detection-severity-framework): `01_info`, `02_low`, `03_medium`, `04_high`, or `05_critical`.","type":"string","enum":["01_info","02_low","03_medium","04_high","05_critical"]},"classification":{"description":"Issue classification (safe, malicious, spam, unknown), or null if not yet classified.","anyOf":[{"type":"string","enum":["safe","malicious","spam","unknown"]},{"type":"null"}]},"analysis":{"title":"APIAnalysis","description":"The analysis results for this issue, including insight tags that describe the threat category and techniques.","$ref":"#/components/schemas/APIAnalysis"},"primaryEntity":{"title":"APIPrimaryEntity","description":"The primary entity associated with this issue. Exactly one of the optional fields will be populated based on `type`.","$ref":"#/components/schemas/APIPrimaryEntity"},"keyEvents":{"title":"APIKeyEvents","description":"The key lifecycle timestamps for this issue, including when it was created, opened, and last updated.","$ref":"#/components/schemas/APIKeyEvents"},"tenantId":{"description":"The encoded tenant ID. Format: `tnt.1.`. Null if no tenant is associated.","anyOf":[{"type":"string"},{"type":"null"}]},"detection":{"title":"APIDetection","description":"The detection rule that triggered this issue.","$ref":"#/components/schemas/APIDetection"},"assigneeId":{"description":"The encoded account ID of the assignee. Format: `acct.1.`. Null if the issue is unassigned.","anyOf":[{"type":"string"},{"type":"null"}]},"ignoreReason":{"description":"Why the status was set to \"ignored\", or null if status is not \"ignored\".","anyOf":[{"type":"string","enum":["false_positive","exception","automatic"]},{"type":"null"}]},"snoozedUntil":{"description":"When the snoozed issue will reopen. Null if the issue is not snoozed.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"supportedRemediations":{"description":"The types of remediation action that can be put in the `remediation` list.","type":"array","items":{"type":"string","enum":["email_threat"]}},"remediation":{"description":"The remediation to apply to the issue. The order does not matter. Each must have a `type` from `supportedRemediations`.","type":"array","items":{"description":"Remediation actions that can be applied to an issue, when the type is in `issue.supportedRemediations`.","oneOf":[{"description":"Remediation actions available for issues with `detection.type=\"email_threat\"`.","oneOf":[{"description":"Remove the message from the mailbox, and any calendar events it created.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"delete"}},"required":["type","action"]},{"description":"Remove any calendar events the message created, but leave the message in the mailbox.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"deleteCalendarEvents"}},"required":["type","action"]},{"description":"Move the message into the spam folder.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"moveToSpam"}},"required":["type","action"]},{"description":"Add a warning banner to the top of the message.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"addBanner"},"message":{"description":"The message to put in the banner. If unset, a default is used.","type":"string"}},"required":["type","action"]},{"description":"Redirect links and attachments to a warning page.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"redirectLinksAndAttachments"},"mode":{"description":"If \"block\", the content is inaccessible. If \"speedbump\", the user may choose whether to continue to the content after reading the warning.","type":"string","enum":["block","speedbump"]}},"required":["type","action","mode"]},{"description":"Send a response to users that report the message as suspicious.","type":"object","properties":{"type":{"type":"string","const":"email_threat"},"action":{"type":"string","const":"respondToReporters"},"message":{"description":"The message to send to reporting users.","type":"string"},"sendToPreviousReporters":{"description":"If false / missing, only send to new reporters going forward. If true, also immediately send to all previous reporters.","type":"boolean"}},"required":["type","action"]}],"type":"object"}],"type":"object"}},"comments":{"description":"Issue comments. Populated when `include=comments`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIIssueComment"}}},"required":["meta","items"]},"accounts":{"description":"The accounts associated with this issue. Populated only when `include=accounts` is specified.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIAccountSummary"}}},"required":["meta","items"]},"messages":{"description":"Related messages. Populated when `include=messages`.","type":"object","properties":{"meta":{"type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]},"numLinks":{"description":"Number of links found in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"numAttachments":{"description":"Number of file attachments in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["numLinks","numAttachments"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIMessageItem"}}},"required":["meta","items"]},"files":{"description":"Related files. Populated when `include=files`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIFileSummary"}}},"required":["meta","items"]}},"required":["id","name","status","severity","classification","analysis","primaryEntity","keyEvents","tenantId","detection","assigneeId","ignoreReason","snoozedUntil","supportedRemediations","remediation"]},"APIAnalysis":{"title":"APIAnalysis","type":"object","properties":{"insights":{"description":"Analysis insight tags. Prefixed by type: `category.*`, `subcategory.*`, `ttp.*`. Example: `category.credential_phishing`, `ttp.link_based`.","type":"array","items":{"type":"string"}}},"required":["insights"]},"APIPrimaryEntity":{"title":"APIPrimaryEntity","type":"object","properties":{"type":{"description":"The entity type. Determines which optional field is populated.","type":"string","enum":["tenant","account","group","file","message","app"]},"account":{"description":"Present when `type` is `account`","$ref":"#/components/schemas/APIAccountEntity"},"message":{"description":"Present when `type` is `message`","$ref":"#/components/schemas/APIMessageEntity"},"file":{"description":"Present when `type` is `file`","$ref":"#/components/schemas/APIFileEntity"},"tenant":{"description":"Present when `type` is `tenant`","$ref":"#/components/schemas/APITenantEntity"},"group":{"description":"Present when `type` is `group`","$ref":"#/components/schemas/APIGroupEntity"},"app":{"description":"Present when `type` is `app`","$ref":"#/components/schemas/APIAppEntity"}},"required":["type"]},"APIAccountEntity":{"title":"APIAccountEntity","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"email":{"description":"The Email address of the account. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"displayName":{"description":"The display name of the account holder. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","email","displayName"]},"APIMessageEntity":{"title":"APIMessageEntity","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"date":{"description":"Message date in ISO 8601 format","type":"string","format":"date-time"},"from":{"description":"Sender email address","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","date","from"]},"APIFileEntity":{"title":"APIFileEntity","type":"object","properties":{"id":{"description":"The encoded file ID. Format: `file.1.`.","type":"string"},"name":{"description":"File name","anyOf":[{"type":"string"},{"type":"null"}]},"mimeType":{"description":"MIME type (e.g. `application/pdf`)","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","mimeType"]},"APITenantEntity":{"title":"APITenantEntity","type":"object","properties":{"csp":{"description":"Cloud service provider (`microsoft` or `google`)","anyOf":[{"type":"string","enum":["microsoft","google"]},{"type":"null"}]}},"required":["csp"]},"APIGroupEntity":{"title":"APIGroupEntity","type":"object","properties":{"name":{"description":"Group name","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"]},"APIAppEntity":{"title":"APIAppEntity","type":"object","properties":{"appType":{"description":"Application type","type":"string","enum":["oauth-token-grant","email-app"]}},"required":["appType"]},"APIKeyEvents":{"title":"APIKeyEvents","type":"object","properties":{"created":{"description":"When the issue was first created","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]},"opened":{"description":"When the issue was last opened","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]},"statusChanged":{"description":"When the issue status last changed","type":"object","properties":{"at":{"description":"ISO 8601 timestamp of the event","type":"string","format":"date-time"}},"required":["at"]}},"required":["created","opened","statusChanged"]},"APIDetection":{"title":"APIDetection","type":"object","properties":{"id":{"description":"The encoded detection ID. Format: `det.1.`.","type":"string"},"name":{"description":"The display name of the detection rule. Null if the rule is unnamed.","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"description":"Detection type: `vulnerability`, `threat`, or `email_threat`.","type":"string","enum":["vulnerability","threat","email_threat"]}},"required":["id","name","type"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APIIssueComment":{"title":"APIIssueComment","type":"object","properties":{"comment":{"description":"Comment text","type":"string"},"author":{"description":"Author name or email","type":"string"},"timestamp":{"description":"When the comment was posted","type":"string","format":"date-time"}},"required":["comment","author","timestamp"]},"APIAccountSummary":{"title":"APIAccountSummary","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"email":{"description":"Email address (included with `include=accounts.email`)","type":"string"},"displayName":{"description":"Display name (included with `include=accounts.displayName`)","type":"string"}},"required":["id"]},"APIMessageItem":{"title":"APIMessageItem","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"headers":{"$ref":"#/components/schemas/APIMessageItemHeaders"}},"required":["id"]},"APIMessageItemHeaders":{"title":"APIMessageItemHeaders","type":"object","properties":{"date":{"description":"The date the message was sent, in ISO 8601 format.","type":"string","format":"date-time"},"from":{"description":"The sender address of the message. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["date","from"]},"APIFileSummary":{"title":"APIFileSummary","type":"object","properties":{"id":{"description":"The encoded file ID. Format: `file.1.`.","type":"string"},"name":{"description":"File name (included with `include=files.name`)","type":"string"},"mimeType":{"description":"MIME type (included with `include=files.mimeType`)","type":"string"}},"required":["id"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/issues/{id}":{"patch":{"operationId":"patchIssue","summary":"Update Issue","description":"Updates the status, classification, assignee, or remediation actions on an existing issue. Only fields included in the request body are changed. Supports setting ignore reasons, snooze windows, and email threat remediation actions such as deleting messages, adding warning banners, or redirecting links and attachments.","tags":["Issues"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the issue to retrieve. Format: `iss.1.`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the issue to retrieve. Format: `iss.1.`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIssueBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIIssue"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## List Issue Messages > Retrieves the paginated list of email messages associated with a specific issue. The response includes link and attachment counts across all related messages, useful for quickly assessing the scope of a threat. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Issues","description":"\nThe Issues API provides programmatic access to security [issues](https://docs.material.security/getting-started/fundamentals/investigate) detected by Material. Query and paginate issues, filter by status, drill down into a specific issue for details including severity and classification, and retrieve the associated email messages along with link and attachment counts.\n\nThese endpoints make up the Issues API:\n\n* **[List Issues](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues)** (`GET /api/v1/issues`): filter and retrieve a paginated list of issues \n* **[Get Issue](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id)** (`GET /api/v1/issues/{id}`): retrieve a single issue by its encoded ID \n* **[List Issue Messages](https://docs.material.security/reference/api-v1/issues#get-api-v1-issues-id-messages)** (`GET /api/v1/issues/{id}/messages`): retrieve the email messages associated with a specific issue\n* **[Update Issue](https://docs.material.security/reference/api-v1/issues#patch-api-v1-issues-id)** (`PATCH /api/v1/issues/{id}`): update the status, classification, assignee, or remediation actions on an existing issue\n\n**Response Structure**\n\nMost Issues API responses (except **Update Issue**) follow a consistent two-part structure:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination. \n* **`items`**: an array containing the actual results, such as issues or messages.\n\nThis pattern applies to all paginated endpoints, as well as to nested collections within a single issue response, for example, `comments`, `accounts`, `messages`, and `files` each return their own `meta` and `items` when requested via the `include` parameter.\n\n**The `include` Parameter**\n\nBy default, issue responses return a core set of fields: ID, name, status, severity, classification, detection rule, primary entity, and key lifecycle timestamps. To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter. Supported values are `comments`, `accounts`, `messages`, and `files`. Pass multiple values as a comma-separated list (e.g. `include=comments,accounts`).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request. \n* The `limit` parameter controls page size on all paginated endpoints. \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set. \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APIMessageItem":{"title":"APIMessageItem","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.`.","type":"string"},"headers":{"$ref":"#/components/schemas/APIMessageItemHeaders"}},"required":["id"]},"APIMessageItemHeaders":{"title":"APIMessageItemHeaders","type":"object","properties":{"date":{"description":"The date the message was sent, in ISO 8601 format.","type":"string","format":"date-time"},"from":{"description":"The sender address of the message. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["date","from"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/issues/{id}/messages":{"get":{"operationId":"listIssueMessages","summary":"List Issue Messages","description":"Retrieves the paginated list of email messages associated with a specific issue. The response includes link and attachment counts across all related messages, useful for quickly assessing the scope of a threat.","tags":["Issues"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the issue to retrieve. Format: `iss.1.`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the issue to retrieve. Format: `iss.1.`."},{"in":"query","name":"include","schema":{"description":"A comma-separated list of additional fields to include in the response. Valid values: `comments`, `accounts`, `messages`, `files`. Use dot notation to select sub-fields (for example, `accounts.email`). Use `*` to include all available fields.","type":"string"},"description":"A comma-separated list of additional fields to include in the response. Valid values: `comments`, `accounts`, `messages`, `files`. Use dot notation to select sub-fields (for example, `accounts.email`). Use `*` to include all available fields."},{"in":"query","name":"cursor","schema":{"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.","type":"string"},"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results."},{"in":"query","name":"limit","schema":{"description":"The maximum number of items to return per page.","type":"integer"},"description":"The maximum number of items to return per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]},"numLinks":{"description":"Number of links found in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"numAttachments":{"description":"Number of file attachments in related messages","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["numLinks","numAttachments"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIMessageItem"}}},"required":["meta","items"]}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` --- # 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://docs.material.security/reference/api-v1/issues.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.