> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/cases-apis/cases.md).

# Cases

Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases.

## Retrieve cases based on filters

> This endpoint retrieves a list of cases that match the specified filter criteria. It supports filtering, sorting, and pagination.\
> \
> \### Supported Filter Fields & Operators\
> \
> See the \[Supported Filter Fields & Operators]\(<https://app.gitbook.com/s/1ZrobAtcwfCDWAJAWeuj/cases-apis/cases-papi-tables#supported-filter-fields-operators>) for more details.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/case/search":{"post":{"summary":"Retrieve cases based on filters","description":"This endpoint retrieves a list of cases that match the specified filter criteria. It supports filtering, sorting, and pagination.\n\n### Supported Filter Fields & Operators\n\nSee the [Supported Filter Fields & Operators](https://app.gitbook.com/s/1ZrobAtcwfCDWAJAWeuj/cases-apis/cases-papi-tables#supported-filter-fields-operators) for more details.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","operationId":"getCases","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["case_id","starred","case_domain","severity","creation_time","last_update_time","modification_time","status_progress","assigned_user","assigned_user_pretty","asset_ids","asset_names","asset_classes","asset_group_ids","asset_categories","asset_regions","asset_providers","asset_accounts","asset_types","asset_cloud_account_names","asset_external_provider_ids","asset_group_names","asset_tags"],"description":"Specifies the field to filter cases by. See the endpoint description for supported operators per field.\n\nNote: last_update_time is still accepted for backward compatibility but is deprecated and not recommended for use. Use modification_time instead."},"operator":{"type":"string","enum":["in","nin","gte","lte","eq","contains","not_contains","neq","json_eq","json_neq"],"description":"Comparison operator. Allowed operators depend on the field:\n- `in`, `nin`: For `case_id`, `case_domain`, `severity`, `status_progress`, `assigned_user`, `assigned_user_pretty`.\n- `gte`, `lte`, `eq`, `neq`: For time fields (`creation_time`, `modification_time`, `last_update_time`). Note: `last_update_time` is deprecated; use `modification_time` instead.\n- `contains`, `not_contains`: For asset fields (`asset_ids`, `asset_names`, `asset_classes`, `asset_group_ids`, `asset_categories`, `asset_regions`, `asset_providers`, `asset_accounts`, `asset_types`, `asset_cloud_account_names`, `asset_external_provider_ids`, `asset_group_names`).\n- `json_eq`, `json_neq`: For `asset_tags` (use an object value with `key` and `value` properties)."},"value":{"description":"Value(s) for filtering the cases. For asset_tags filtering with json_eq/json_neq, use an object with key and value properties.","oneOf":[{"type":"array","items":{"type":"integer"}},{"type":"array","items":{"type":"string"}},{"type":"integer"},{"type":"string"},{"type":"boolean"},{"type":"object","properties":{"key":{"type":"string","description":"Tag key to match (for json_eq/json_neq on asset_tags)"},"value":{"type":"string","description":"Tag value to match (for json_eq/json_neq on asset_tags)"}},"required":["key","value"],"description":"Key-value pair for asset_tags filtering. Both 'key' and 'value' are required."}]}}}},"search_from":{"type":"integer","description":"Starting index for pagination.","default":0},"search_to":{"type":"integer","description":"Ending index for pagination.","default":100},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["case_id","severity","creation_time","modification_time"]},"keyword":{"type":"string","enum":["asc","desc"],"description":"Sort order (ascending or descending)."}}}}}}}}}},"responses":{"200":{"description":"Successful response with cases","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"TOTAL_COUNT":{"type":"integer"},"FILTER_COUNT":{"type":"integer"},"DATA":{"type":"array","items":{"$ref":"#/components/schemas/Case"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Cases"]}}},"components":{"schemas":{"Case":{"type":"object","properties":{"case_id":{"type":"integer","description":"Unique identifier for the case"},"is_blocked":{"type":"boolean","description":"Indicates if the case is blocked due to RBAC restrictions"},"case_name":{"type":"string","description":"Name of the case"},"creation_time":{"type":"integer","format":"int64","description":"Timestamp of case creation in epoch milliseconds"},"modification_time":{"type":"integer","format":"int64","description":"Timestamp of last modification in epoch milliseconds"},"status_progress":{"type":"string","description":"Current status of the case. Built-in values are 'New', 'In Progress', and 'Resolved'. Additional custom statuses may be configured per tenant and case domain."},"resolve_reason":{"type":"string","nullable":true,"description":"Resolution reason when the case is resolved. Null when the case is not resolved. Built-in values include 'Resolved - Known Issue', 'Resolved - Duplicate Case', 'Resolved - False Positive', 'Resolved - Other', 'Resolved - True Positive', 'Resolved - Security Testing'. Additional values such as 'Resolved - Dismissed', 'Resolved - Fixed', and 'Resolved - Risk Accepted' may be available depending on tenant licensing. Custom resolution reasons may also be configured per tenant and case domain."},"severity":{"type":"string","enum":["info","low","medium","high","critical"],"description":"Severity level of the case (lowercase)"},"description":{"type":"string","nullable":true,"description":"Detailed description of the case. May be null if no description is set."},"assigned_user_mail":{"type":"string","nullable":true,"description":"Email address of the assigned user. Null if no user is assigned."},"assigned_user_pretty_name":{"type":"string","nullable":true,"description":"Display name of the assigned user. Null if no user is assigned."},"issue_count":{"type":"integer","description":"Total number of issues in the case"},"user_severity":{"type":"string","nullable":true,"enum":["low","medium","high","critical"],"description":"User-defined severity override (lowercase). Null if not set. Allowed values: 'low', 'medium', 'high', 'critical'."},"notes":{"type":"string","nullable":true,"description":"Free-text notes associated with the case. Null if not set."},"low_severity_issue_count":{"type":"integer","description":"Number of low severity issues"},"med_severity_issue_count":{"type":"integer","description":"Number of medium severity issues"},"high_severity_issue_count":{"type":"integer","description":"Number of high severity issues"},"critical_severity_issue_count":{"type":"integer","description":"Number of critical severity issues"},"user_count":{"type":"integer","description":"Number of users associated with the case"},"host_count":{"type":"integer","description":"Number of hosts associated with the case"},"resolve_comment":{"type":"string","nullable":true,"description":"Free-text comment provided when resolving the case. Null when the case is not resolved or no comment was provided."},"resolved_timestamp":{"type":"integer","format":"int64","nullable":true,"description":"Timestamp when the case was resolved in epoch milliseconds"},"xdr_url":{"type":"string","description":"URL to view the case in the Cortex console"},"starred":{"type":"boolean","description":"Indicates if the case is starred"},"hosts":{"type":"array","nullable":true,"items":{"type":"string"},"description":"List of hosts associated with the case in format 'hostname:endpoint_id'"},"users":{"type":"array","nullable":true,"items":{"type":"string"},"description":"List of users associated with the case"},"aggregated_score":{"type":"integer","nullable":true,"description":"Combined/aggregated score assigned to the case"},"wildfire_hits":{"type":"integer","description":"Number of WildFire hits"},"mitre_tactics_ids_and_names":{"type":"array","nullable":true,"items":{"type":"string"},"description":"List of MITRE ATT&CK tactics IDs and names"},"mitre_techniques_ids_and_names":{"type":"array","nullable":true,"items":{"type":"string"},"description":"List of MITRE ATT&CK techniques IDs and names"},"issue_categories":{"type":"array","nullable":true,"items":{"type":"string"},"description":"List of issue categories in the case"},"tags":{"type":"array","items":{"type":"string"},"description":"List of tags associated with the case"},"custom_fields":{"type":"object","nullable":true,"additionalProperties":true,"description":"Custom fields for additional metadata"},"asset_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"List of asset IDs associated with the case"},"asset_group_ids":{"type":"array","items":{"type":"string"},"description":"List of asset group IDs associated with the case"},"asset_group_names":{"type":"array","items":{"type":"string"},"description":"List of asset group names associated with the case"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"},"description":"List of asset objects associated with the case"},"case_domain":{"type":"string","description":"Domain associated with the case"},"issue_ids":{"type":"array","nullable":true,"items":{"type":"integer"},"description":"List of issue IDs associated with the case"},"file_artifact_ids":{"type":"object","description":"File artifact IDs associated with the case","properties":{"DATA":{"type":"array","items":{"type":"string"},"description":"List of file artifact hash IDs"},"TOTAL_COUNT":{"type":"integer","description":"Total count of file artifacts"}}},"network_artifact_ids":{"type":"object","description":"Network artifact IDs associated with the case","properties":{"DATA":{"type":"array","items":{"type":"string"},"description":"List of network artifact IDs"},"TOTAL_COUNT":{"type":"integer","description":"Total count of network artifacts"}}},"case_team":{"type":"array","description":"Team members assigned to the case.","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the team member (user email or group id)."},"member_type":{"type":"string","enum":["USER","GROUP"],"description":"Type of the team member."},"team_role":{"type":"string","enum":["OWNER","MEMBER"],"description":"Role of the team member."}}}},"access_mode":{"type":"string","enum":["CASE_SCOPE","TEAM_ONLY"],"description":"Access mode for the case. CASE_SCOPE: standard SBAC. TEAM_ONLY: restrict to case_team members."}}},"Asset":{"type":"object","description":"Asset object associated with a case","properties":{"asset_id":{"type":"string","description":"Unique identifier for the asset"},"asset_name":{"type":"string","description":"Name of the asset"},"asset_type":{"type":"string","description":"Type of the asset"},"asset_region":{"type":"string","description":"Cloud region where the asset is located"},"asset_group_ids":{"type":"array","items":{"type":"integer"},"description":"List of asset group IDs"},"asset_provider":{"type":"string","description":"Cloud provider"},"asset_account":{"type":"string","description":"Cloud account identifier"},"asset_category":{"type":"string","description":"Category of the asset"},"asset_cloud_account_name":{"type":"string","description":"Cloud account name"},"asset_external_provider_id":{"type":"string","description":"External provider ID for the asset"},"asset_tags":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value tags associated with the asset"},"asset_group_names":{"type":"array","items":{"type":"string"},"description":"Names of the asset groups this asset belongs to"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## Update existing case

> Update an existing case in the system. \*\*Users can only update one case at a time.\*\*\
> \
> At least one valid update field must be provided in \`update\_data\`. An empty \`update\_data\` object will return a 400 error. All field values must be non-null.\
> \
> \### Update Fields\
> \
> See the \[Update Fields]\(<https://app.gitbook.com/s/1ZrobAtcwfCDWAJAWeuj/cases-apis/cases-papi-tables#update-fields>) for more details.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/case/update/{case-id}":{"post":{"summary":"Update existing case","description":"Update an existing case in the system. **Users can only update one case at a time.**\n\nAt least one valid update field must be provided in `update_data`. An empty `update_data` object will return a 400 error. All field values must be non-null.\n\n### Update Fields\n\nSee the [Update Fields](https://app.gitbook.com/s/1ZrobAtcwfCDWAJAWeuj/cases-apis/cases-papi-tables#update-fields) for more details.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","operationId":"updateCase","parameters":[{"name":"case-id","in":"path","description":"Numeric ID of the case to update","required":true,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"update_data":{"$ref":"#/components/schemas/UpdateCase"}}}}}}}},"responses":{"204":{"description":"Case updated successfully"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Cases"]}}},"components":{"schemas":{"UpdateCase":{"type":"object","properties":{"status_progress":{"type":"string","description":"Status to set on the case. Built-in values: 'New', 'In Progress', 'Resolved'. Values are case-insensitive. Additional custom statuses may be configured per tenant and case domain. If an invalid status is provided, the API will return an error listing the valid options."},"resolve_reason":{"type":"string","description":"Resolution reason when status_progress is set to 'Resolved'. Required when resolving a case. The built-in values listed below may vary per tenant and case domain; additional custom resolution reasons may also be available. If an invalid value is provided, the API will return an error listing the valid options for that specific case.","enum":["Resolved - Known Issue","Resolved - Duplicate Case","Resolved - False Positive","Resolved - Other","Resolved - True Positive","Resolved - Security Testing"]},"resolve_comment":{"type":"string","description":"Free-text comment to add when resolving the case. Only applicable when status_progress is set to 'Resolved'."},"notes":{"type":"string","description":"Free-text notes associated with the case. Can be set independently of status changes."},"user_severity":{"type":"string","description":"User-defined severity override (lowercase). Use an empty string to clear the severity. Allowed values: 'low', 'medium', 'high', 'critical'.","enum":["low","medium","high","critical"]},"assigned_user":{"type":"string","description":"Email address of the user to assign the case to. Must be a valid Cortex XDR user email."},"case_team":{"type":"array","description":"Team members assigned to the case.","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the team member (user email or group id)."},"member_type":{"type":"string","enum":["USER","GROUP"],"description":"Type of the team member."},"team_role":{"type":"string","enum":["OWNER","MEMBER"],"description":"Role of the team member."}}}},"access_mode":{"type":"string","enum":["CASE_SCOPE","TEAM_ONLY"],"description":"Access mode for the case. CASE_SCOPE: standard SBAC. TEAM_ONLY: restrict to case_team members."}},"additionalProperties":{"description":"Custom field values. Use the custom field name as the property key."}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## Retrieve case artifacts

> This endpoint retrieves the artifacts for a given case\_id.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/case/artifacts/{case-id}/":{"get":{"summary":"Retrieve case artifacts","description":"This endpoint retrieves the artifacts for a given case_id.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","operationId":"getCaseArtifacts","parameters":[{"name":"case-id","in":"path","description":"Numeric ID of the case","required":true,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response with case artifacts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CaseArtifact"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Cases"]}}},"components":{"schemas":{"CaseArtifact":{"type":"object","properties":{"case_id":{"type":"integer","description":"Case ID for which the artifacts are fetched"},"network_artifacts":{"type":"object","properties":{"DATA":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"TOTAL_COUNT":{"type":"integer"}}},"file_artifacts":{"type":"object","properties":{"DATA":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"TOTAL_COUNT":{"type":"integer"}}}}},"Artifact":{"type":"object","properties":{"artifact_id":{"type":"string","description":"Unique identifier for the artifact"},"file_name":{"type":"string","description":"File name for the artifact"},"file_sha256":{"type":"string","description":"File sha256 for the artifact"},"file_signature_status":{"type":"string","description":"File signature for the artifact"},"file_wildfire_verdict":{"type":"string","description":"File wildfire verdict for the artifact"},"is_malicious":{"type":"boolean","description":"Indicates if the artifact is malicious"},"is_manual":{"type":"boolean","description":"Indicates if the artifact is manual"},"is_process":{"type":"boolean","description":"Indicates if the artifact is related to a process"},"low_confidence":{"type":"boolean","description":"Indicates the artifact confidence"},"type":{"type":"string","description":"Type of the artifact"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## Get cases schema

> Returns the schema of all available case fields, including core fields and tenant-specific custom fields. Each entry includes the field name, a human-readable display name, and the data type.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/case/schema":{"get":{"summary":"Get cases schema","description":"Returns the schema of all available case fields, including core fields and tenant-specific custom fields. Each entry includes the field name, a human-readable display name, and the data type.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","operationId":"getCasesSchema","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response with cases schema","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"array","items":{"$ref":"#/components/schemas/CaseSchemaField"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"tags":["Cases"]}}},"components":{"schemas":{"CaseSchemaField":{"type":"object","description":"Describes a single field in the cases schema","properties":{"field_name":{"type":"string","description":"Internal field name used to identify the case field"},"field_pretty_name":{"type":"string","description":"Human-readable display name for the field"},"data_type":{"type":"string","description":"Data type of the field value (e.g. TEXT, INT, TIMESTAMP, BOOLEAN, ARRAY, JSON)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized access","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}
```

## Retrieve case timeline records

> Retrieve the timeline records for a specific case. Supports filtering, sorting, and pagination. Returns flat timeline records (no clustering).\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/case/timeline/{case-id}/":{"post":{"summary":"Retrieve case timeline records","tags":["Cases"],"operationId":"getCaseTimeline","description":"Retrieve the timeline records for a specific case. Supports filtering, sorting, and pagination. Returns flat timeline records (no clustering).\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","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},{"schema":{"type":"string"},"name":"case-id","description":"Numeric ID of the case","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","description":"Request parameters used to filter, sort, and paginate case timeline records.","properties":{"filters":{"type":"array","description":"Filter conditions to limit the timeline records returned in the response. You can specify one or more filters.","items":{"type":"object","properties":{"field":{"type":"string","enum":["record_type","record_subtype","record_name","source","source_id","record_id","occurred_at","creation_time","is_evidence","evidence_comment","evidence_flag_time","evidence_flag_by","tags","timelines"],"description":"Specifies the timeline record field to filter. See the [Case timeline record filter fields and operators](https://app.gitbook.com/s/1ZrobAtcwfCDWAJAWeuj/cases-apis/cases-papi-tables#case-timeline-record-filter-fields-and-operators) section for details on the available fields and their supported operators."},"operator":{"type":"string","enum":["in","nin","eq","neq","gte","lte","contains","not_contains"],"description":"comparison operator to apply to the selected field. The available operators depend on the field type."},"value":{"description":"value to use when applying the filter condition. The API accepts single values or arrays of values depending on the selected field and operator.","oneOf":[{"type":"array","items":{"type":"string"}},{"type":"integer"},{"type":"string"},{"type":"boolean"}]}}}},"search_from":{"type":"integer","description":"Zero-based index of the first record to return. This is a record offset, not a page number. For example, set `search_from` = 100 to start returning records from the 101st record.","default":0},"search_to":{"type":"integer","description":"Zero-based index where the result set ends (exclusive). This is a record offset, not a page number. For example, set `search_to` = 200 to return records up to, but not including, the 201st record.","default":100},"sort":{"type":"object","description":"Sorting options for the returned timeline records.","properties":{"field":{"type":"string","enum":["occurred_at","creation_time","record_type","record_subtype","record_name","source","source_id","is_evidence","evidence_comment","evidence_flag_time","evidence_flag_by"],"description":"Timeline record field to use for sorting"},"keyword":{"description":"Sort direction for the selected field. (ascending or descending). Defaults to `desc`.","type":"string","enum":["asc","dsc"]}}}}}}}}}},"responses":{"200":{"description":"OK. Request Successful.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","description":"Timeline query response data and metadata.","properties":{"DATA":{"type":"array","description":"List of timeline records matching the specified filters, sorting, and pagination parameters.","items":{"type":"object","properties":{"record_id":{"type":"string","description":"Unique identifier of the timeline record."},"record_name":{"type":"string","description":"Display name / title of the record"},"description":{"type":"string","description":"Description of the record.","nullable":true},"record_type":{"type":"string","description":"High-level category of the timeline record. Possible values include `Detection`, `Response`, `Case activity`, `Automation`, and `System update`."},"record_subtype":{"type":"string","description":"Specific event type within the record category.","nullable":true},"timelines":{"type":"array","description":"Timeline labels associated with the record.","items":{"type":"string"}},"tags":{"type":"array","description":"Tags associated with the timeline record.","items":{"type":"string"}},"source":{"type":"string","description":"Origin of the record"},"source_id":{"type":"string","description":"Identifier of the entity that generated the record.","nullable":true},"creation_time":{"type":"integer","description":"Timestamp when the record was created, in epoch milliseconds.","nullable":true},"occurred_at":{"type":"integer","description":"Timestamp when the event occurred, in epoch milliseconds."},"is_evidence":{"type":"boolean","description":"Indicates whether the record is marked as evidence."},"evidence_title":{"type":"string","description":"Title assigned to the evidence record, if applicable.","nullable":true},"evidence_comment":{"type":"string","description":"Comment associated with the evidence.","nullable":true},"evidence_flag_time":{"type":"integer","description":"Timestamp when the record was marked as evidence, in epoch milliseconds.","nullable":true},"evidence_flag_by":{"type":"string","description":"User or entity that marked the record as evidence.","nullable":true},"attachments":{"type":"array","description":"Files or attachments associated with the timeline record.","nullable":true,"items":{"type":"object","properties":{"filename":{"type":"string","description":"Name of the attached file."}}}},"query_execution_id":{"type":"string","description":"Associated XQL query execution id, if any","nullable":true}}}},"FILTER_COUNT":{"type":"integer","description":"Number of timeline records returned in the current response after applying filters and pagination."},"TOTAL_COUNT":{"type":"integer","description":"Total number of timeline records matching the applied filters before pagination is applied."}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized. ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error.","nullable":true}}}}}}}}
```

## Add a case timeline record

> Adds a manual timeline record to the specified case. The API automatically sets the \`source\` field to \`API Key\` and the \`source\_id\` field to the ID of the API key used for the request.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/case/timeline/{case-id}/add_record/":{"post":{"summary":"Add a case timeline record","tags":["Cases"],"operationId":"addCaseTimelineRecord","description":"Adds a manual timeline record to the specified case. The API automatically sets the `source` field to `API Key` and the `source_id` field to the ID of the API key used for the request.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","required":true,"description":"{api_key}"},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","required":true,"description":"{api_key_id}"},{"schema":{"type":"string"},"name":"case-id","description":"Numeric ID of the case","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","required":["record_type","record_name","occurred_at"],"properties":{"record_type":{"type":"string","enum":["Case activity","Detection","Response"],"description":"High-level category of the timeline record."},"record_name":{"type":"string","description":"Name of the timeline record."},"occurred_at":{"type":"integer","format":"int64","description":"Timestamp when the timeline event occurred, in epoch milliseconds."},"description":{"type":"string","description":"Description of the timeline record."},"is_evidence":{"type":"boolean","description":"Specifies whether to mark the timeline record as evidence."},"evidence_comment":{"type":"string","description":"Comment to associate with the evidence record. Use this field when `is_evidence` is set to `true`."},"tags":{"type":"array","description":"Tags to associate with the timeline record.","items":{"type":"string"}},"timelines":{"type":"array","description":"Timelines to associate with the timeline record.","items":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"OK. The timeline record was created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"record_id":{"type":"string","description":"Unique identifier of the created timeline record."},"case_id":{"type":"integer","description":"Identifier of the case to which the timeline record was added."}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error.","nullable":true}}}}}}}}
```

## Get War Room entries

> Get the War Room entries for a specific case or alert. You can filter by timestamp, ID, and tags. You can also choose which type of entries you want to retrieve (notes, chat, attachments...).\
> The response depends on what type of entry you choose to retrieve.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/entries/get":{"post":{"tags":["Cases"],"summary":"Get War Room entries","description":"Get the War Room entries for a specific case or alert. You can filter by timestamp, ID, and tags. You can also choose which type of entries you want to retrieve (notes, chat, attachments...).\nThe response depends on what type of entry you choose to retrieve.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","operationId":"post-public_api-v1-entries-get","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the case or alert for which the War Room entry is created.\n\n- Case IDs must be prefixed with `INCIDENT-` (for example, `INCIDENT-3`).\n- Alert IDs should be provided without any prefix (for example, `3`)."},"filter":{"type":"object","properties":{"firstID":{"type":"string","description":"Return results starting from the investigation ID in `firstID` until the last investigation ID."},"lastID":{"type":"string","description":"Return results starting from the first investigation ID until the investigation ID in `lastID`."},"pagesize":{"type":"integer","description":"Filter the results by the number of entries you want returned. `\"pagesize\": 0` returns all the results."},"fromTime":{"type":"string","description":"RFC3339 timestamp. Filter results from the time the entry is created until the latest entry."},"categories":{"type":"array","description":"The categories you want to filter and the results you want to receive:\n- `tags`: Tags added to the investigation.\n- `chats`: Communication between team members in the form of chat messages.\n- `notes`: Any entries marked as notes.\n- `attachments`: Any files uploaded to the War Room in a playbook, script, or by the analyst.\n- `incidentInfo`: The case history.\n- `commandAndResults`: Command and return the result of the command.\n- `playbookTaskResult`: Return the task result.\n- `playbookTaskStartAndDone`: Task and return the task result.\n- `playbookErrors`: When there are no playbook errors, the response returned is `0`.","items":{"type":"string","enum":["tags","chats","notes","attachments","incidentInfo","commandAndResults","playbookTaskResult","playbookTaskStartAndDone","playbookErrors"]}},"tags":{"type":"array","description":"If using the filter category of `tags`, include the tags you want to filter by.","items":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"modified":{"type":"string"},"created":{"type":"string"},"user":{"type":"string"},"parentContent":{"type":"string"},"contents":{"type":"string"},"format":{"type":"string"},"investigationId":{"type":"string"},"category":{"type":"string"},"isTodo":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error.","nullable":true}}}}}}}}
```

## Add War Room entries

> Add an entry to the cases or alert War Room, including data.\
> Note: This endpoint only adds entries to existing War Rooms; it does not create them. Ensure that the War Room already exists before making this request.\
> \
> \*\*Required license:\*\* Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.

```json
{"openapi":"3.0.0","info":{"title":"Cases API","version":"Cortex XSIAM 3.6"},"tags":[{"name":"Cases","description":"Cases APIs to search and update cases, retrieve case artifacts, manage War Room entries, retrieve timeline records, and add manual timeline records to cases."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/entries/insert":{"post":{"tags":["Cases"],"summary":"Add War Room entries","description":"Add an entry to the cases or alert War Room, including data.\nNote: This endpoint only adds entries to existing War Rooms; it does not create them. Ensure that the War Room already exists before making this request.\n\n**Required license:** Cortex XSIAM Premium or Cortex XSIAM Enterprise or Cortex XSIAM NG SIEM or Cortex XSIAM Enterprise Plus.","operationId":"post-public_api-v1-entries-insert","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the case/issue or alert for which the War Room entry is created.\n\n- Case or issue IDs must be prefixed with `INCIDENT-` (for example, `INCIDENT-3`).\n- Alert IDs should be provided without any prefix (for example, `3`)."},"data":{"type":"string","description":"The data you want to add or the command you want to run in the War Room."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"cacheVersn":{"type":"integer"},"modified":{"type":"string"},"sizeInBytes":{"type":"integer"},"type":{"type":"integer"},"created":{"type":"string"},"incidentCreationTime":{"type":"string"},"investigationCreationTime":{"type":"string"},"retryTime":{"type":"string"},"user":{"type":"string"},"errorSource":{"type":"string"},"contents":{"type":"string"},"format":{"type":"string"},"investigationId":{"type":"string"},"file":{"type":"string"},"fileID":{"type":"string"},"parentId":{"type":"string"},"pinned":{"type":"boolean"},"fileMetadata":{"type":"object","nullable":true},"parentContent":{"type":"object","nullable":true},"parentEntryTruncated":{"type":"boolean"},"system":{"type":"string"},"reputations":{"type":"object","nullable":true},"category":{"type":"string"},"note":{"type":"boolean"},"isTodo":{"type":"boolean"},"tags":{"type":"string","nullable":true},"tagsRaw":{"type":"string","nullable":true},"startDate":{"type":"string"},"times":{"type":"integer"},"recurrent":{"type":"boolean"},"endingDate":{"type":"string"},"timezoneOffset":{"type":"integer"},"cronView":{"type":"boolean"},"scheduled":{"type":"boolean"},"scheduledEntryGuid":{"type":"string"},"entryTask":{"type":"object","nullable":true},"taskId":{"type":"string"},"playbookId":{"type":"string"},"reputationSize":{"type":"integer"},"contentsSize":{"type":"integer"},"brand":{"type":"string"},"InstanceID":{"type":"string"},"IndicatorTimeline":{"type":"integer","nullable":true},"Relationships":{"type":"string","nullable":true},"mirrored":{"type":"boolean"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error.","nullable":true}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xsiam-api/cases-apis/cases.md?ask=<question>&goal=<endgoal>
```

`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.