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

# Categories

Operations for retrieving categories and subcategories

## Get categories and subcategories (v1)

> Retrieve available compliance control categories and subcategories.\
> \
> \*\*Required license:\*\* Requires the Cortex Cloud Posture Management add-on.

```json
{"openapi":"3.0.3","info":{"title":"Compliance Controls API","version":"Cortex XDR 5.1"},"tags":[{"name":"Categories","description":"Operations for retrieving categories and subcategories"}],"servers":[{"url":"https://{tenant}.xdr.{region}.paloaltonetworks.com","description":"Cortex tenant","variables":{"tenant":{"default":"api","description":"Tenant-specific subdomain"},"region":{"default":"us","description":"Deployment region","enum":["us","eu","uk","sg","jp","ca","au","in","gov"]}}}],"security":[{"XDRAuth":[],"XDRAuthToken":[]}],"components":{"securitySchemes":{"XDRAuth":{"type":"apiKey","in":"header","name":"x-xdr-auth-id","description":"API Key ID for authentication"}},"responses":{"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message"},"err_extra":{"type":"object","description":"Additional error details"}}}}}}},"paths":{"/public_api/v1/compliance/get_control_categories_and_subcategories":{"post":{"summary":"Get categories and subcategories (v1)","description":"Retrieve available compliance control categories and subcategories.\n\n**Required license:** Requires the Cortex Cloud Posture Management add-on.","operationId":"getCategoriesAndSubcategories","tags":["Categories"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object"}}}}}},"responses":{"200":{"description":"Successfully retrieved categories and subcategories","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"data":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"},"description":"Available control categories"},"subcategories":{"type":"array","items":{"type":"string"},"description":"Available control subcategories"}}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## List categories (v2)

> Returns categories for a standard. Optionally filter by \`parent\_category\_id\` to list only\
> subcategories of a specific parent.\
> Requires \`platform\_compliance\_view\` permission.\
> \
> \
> \*\*Required license:\*\* Requires the Cortex Cloud Posture Management add-on.

```json
{"openapi":"3.0.3","info":{"title":"Compliance Controls API","version":"Cortex XDR 5.1"},"tags":[{"name":"Categories","description":"Operations for retrieving categories and subcategories"}],"servers":[{"url":"https://{tenant}.xdr.{region}.paloaltonetworks.com","description":"Cortex tenant","variables":{"tenant":{"default":"api","description":"Tenant-specific subdomain"},"region":{"default":"us","description":"Deployment region","enum":["us","eu","uk","sg","jp","ca","au","in","gov"]}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{},"parameters":{"OffsetParam":{"name":"offset","in":"query","required":false,"description":"Pagination offset (0-based)","schema":{"type":"integer","minimum":0,"default":0}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return (PAPI). Default 50, max 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}},"schemas":{"PapiPaginatedResponse":{"type":"object","description":"PAPI pagination envelope","required":["total_count","results"],"properties":{"total_count":{"type":"integer","description":"Total number of items matching the query"},"results":{"type":"array","items":{"type":"object"},"description":"Array of result items for the current page"},"next_offset":{"type":"integer","nullable":true,"description":"Offset for the next page, or null if no more results"}}},"Error":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message"},"err_extra":{"type":"object","description":"Additional error details"}}}}}},"responses":{"BadRequest":{"description":"Bad request - invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/public_api/v2/compliance/categories":{"get":{"operationId":"papiListCategories","summary":"List categories (v2)","description":"Returns categories for a standard. Optionally filter by `parent_category_id` to list only\nsubcategories of a specific parent.\nRequires `platform_compliance_view` permission.\n\n\n**Required license:** Requires the Cortex Cloud Posture Management add-on.","tags":["Categories"],"parameters":[{"name":"standard_id","in":"query","required":true,"description":"UUID of the standard to list categories for","schema":{"type":"string","format":"uuid"}},{"name":"parent_category_id","in":"query","required":false,"description":"Filter by parent category ID. Pass a UUID to list subcategories of that parent.\nOmit to list all categories (top-level and subcategories).\n","schema":{"type":"string","format":"uuid","nullable":true}},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Paginated list of categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PapiPaginatedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}}}
```

## Create a category or subcategory (v2)

> Creates a new category within a standard. The \`standard\_id\` must be provided in the\
> request body. To create a subcategory, set \`parent\_category\_id\` to the UUID of an\
> existing top-level category. Max 2 nesting levels (category → subcategory).\
> Requires \`platform\_compliance\_edit\` permission.\
> \
> Returns \*\*400\*\* if the parent standard is official (\`is\_custom: false\`).\
> Out-of-the-box standards and their children are immutable from this API.\
> \
> Returns \*\*400\*\* if \`parent\_category\_id\` references a category belonging to a\
> different standard (single-standard-ownership invariant).\
> \
> \
> \*\*Required license:\*\* Requires the Cortex Cloud Posture Management add-on.

```json
{"openapi":"3.0.3","info":{"title":"Compliance Controls API","version":"Cortex XDR 5.1"},"tags":[{"name":"Categories","description":"Operations for retrieving categories and subcategories"}],"servers":[{"url":"https://{tenant}.xdr.{region}.paloaltonetworks.com","description":"Cortex tenant","variables":{"tenant":{"default":"api","description":"Tenant-specific subdomain"},"region":{"default":"us","description":"Deployment region","enum":["us","eu","uk","sg","jp","ca","au","in","gov"]}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{},"schemas":{"PapiCategoryCreate":{"type":"object","description":"PAPI request body for creating a category.","required":["standard_id","name"],"properties":{"standard_id":{"type":"string","format":"uuid","description":"UUID of the parent standard"},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Category name"},"description":{"type":"string","maxLength":2048,"nullable":true,"description":"Optional description"},"parent_category_id":{"type":"string","format":"uuid","nullable":true,"description":"Set to a top-level category UUID to create a subcategory.\nSet to `null` or omit to create a top-level category.\n"}}},"PapiCategoryResponse":{"type":"object","description":"PAPI response model for a compliance category.","required":["id","standard_id","name","created_at","created_by"],"properties":{"id":{"type":"string","format":"uuid","description":"System-generated UUID v4"},"standard_id":{"type":"string","format":"uuid","description":"UUID of the parent standard"},"parent_category_id":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the parent category (null for top-level categories)"},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Category name"},"description":{"type":"string","maxLength":2048,"nullable":true,"description":"Optional description"},"created_at":{"type":"integer","description":"Creation timestamp (epoch seconds)"},"modified_at":{"type":"integer","nullable":true,"description":"Last modification timestamp (epoch seconds)"},"created_by":{"type":"string","description":"User who created the resource"},"modified_by":{"type":"string","nullable":true,"description":"User who last modified the resource"}}},"ErrorResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message describing what went wrong"},"err_extra":{"type":"object","description":"Additional error details"}},"required":["err_code","err_msg"]}}},"Error":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message"},"err_extra":{"type":"object","description":"Additional error details"}}}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict - duplicate resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/public_api/v2/compliance/categories":{"post":{"operationId":"papiCreateCategory","summary":"Create a category or subcategory (v2)","description":"Creates a new category within a standard. The `standard_id` must be provided in the\nrequest body. To create a subcategory, set `parent_category_id` to the UUID of an\nexisting top-level category. Max 2 nesting levels (category → subcategory).\nRequires `platform_compliance_edit` permission.\n\nReturns **400** if the parent standard is official (`is_custom: false`).\nOut-of-the-box standards and their children are immutable from this API.\n\nReturns **400** if `parent_category_id` references a category belonging to a\ndifferent standard (single-standard-ownership invariant).\n\n\n**Required license:** Requires the Cortex Cloud Posture Management add-on.","tags":["Categories"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PapiCategoryCreate"}}},"description":"Payload for create a category or subcategory"},"responses":{"201":{"description":"Category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PapiCategoryResponse"}}}},"400":{"description":"Bad request. In addition to standard validation errors, returns 400 when:\n- The parent standard is official (`is_custom: false`) — see `official_standard` example.\n- `parent_category_id` references a category belonging to a different standard\n  — see `cross_standard_parent` example.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```

## Update a category or subcategory (v2)

> Updates an existing category. Only \`name\` and \`description\` can be updated;\
> \`parent\_category\_id\` is immutable after creation. Any \`standard\_id\` in the\
> payload is silently stripped server-side (re-parenting is rejected by the\
> single-standard-ownership invariant).\
> Requires \`platform\_compliance\_edit\` permission.\
> \
> Returns \*\*400\*\* if the parent standard is official (\`is\_custom: false\`).\
> Out-of-the-box standards and their children are immutable from this API.\
> \
> \
> \*\*Required license:\*\* Requires the Cortex Cloud Posture Management add-on.

```json
{"openapi":"3.0.3","info":{"title":"Compliance Controls API","version":"Cortex XDR 5.1"},"tags":[{"name":"Categories","description":"Operations for retrieving categories and subcategories"}],"servers":[{"url":"https://{tenant}.xdr.{region}.paloaltonetworks.com","description":"Cortex tenant","variables":{"tenant":{"default":"api","description":"Tenant-specific subdomain"},"region":{"default":"us","description":"Deployment region","enum":["us","eu","uk","sg","jp","ca","au","in","gov"]}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{},"schemas":{"PapiCategoryUpdate":{"type":"object","description":"PAPI request body for updating a category. Only `name` and `description`\ncan be updated; `parent_category_id` is immutable.\n","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Updated category name"},"description":{"type":"string","maxLength":2048,"nullable":true,"description":"Updated description"}}},"PapiCategoryResponse":{"type":"object","description":"PAPI response model for a compliance category.","required":["id","standard_id","name","created_at","created_by"],"properties":{"id":{"type":"string","format":"uuid","description":"System-generated UUID v4"},"standard_id":{"type":"string","format":"uuid","description":"UUID of the parent standard"},"parent_category_id":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the parent category (null for top-level categories)"},"name":{"type":"string","minLength":1,"maxLength":256,"description":"Category name"},"description":{"type":"string","maxLength":2048,"nullable":true,"description":"Optional description"},"created_at":{"type":"integer","description":"Creation timestamp (epoch seconds)"},"modified_at":{"type":"integer","nullable":true,"description":"Last modification timestamp (epoch seconds)"},"created_by":{"type":"string","description":"User who created the resource"},"modified_by":{"type":"string","nullable":true,"description":"User who last modified the resource"}}},"ErrorResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message describing what went wrong"},"err_extra":{"type":"object","description":"Additional error details"}},"required":["err_code","err_msg"]}}},"Error":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message"},"err_extra":{"type":"object","description":"Additional error details"}}}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict - duplicate resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/public_api/v2/compliance/categories/{category_id}":{"post":{"operationId":"papiUpdateCategory","summary":"Update a category or subcategory (v2)","description":"Updates an existing category. Only `name` and `description` can be updated;\n`parent_category_id` is immutable after creation. Any `standard_id` in the\npayload is silently stripped server-side (re-parenting is rejected by the\nsingle-standard-ownership invariant).\nRequires `platform_compliance_edit` permission.\n\nReturns **400** if the parent standard is official (`is_custom: false`).\nOut-of-the-box standards and their children are immutable from this API.\n\n\n**Required license:** Requires the Cortex Cloud Posture Management add-on.","tags":["Categories"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PapiCategoryUpdate"}}},"description":"Payload for update a category or subcategory"},"responses":{"200":{"description":"Category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PapiCategoryResponse"}}}},"400":{"description":"Bad request. In addition to standard validation errors, returns 400 when\nthe parent standard is official (`is_custom: false`) — see\n`official_standard` example.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}}}}
```

## Delete a category (v2)

> Deletes a category and cascades to its subcategories and all associated controls.\
> Requires \`platform\_compliance\_edit\` permission.\
> \
> Returns \*\*400\*\* if the parent standard is official (\`is\_custom: false\`).\
> Out-of-the-box standards and their children are immutable from this API.\
> \
> \
> \*\*Required license:\*\* Requires the Cortex Cloud Posture Management add-on.

```json
{"openapi":"3.0.3","info":{"title":"Compliance Controls API","version":"Cortex XDR 5.1"},"tags":[{"name":"Categories","description":"Operations for retrieving categories and subcategories"}],"servers":[{"url":"https://{tenant}.xdr.{region}.paloaltonetworks.com","description":"Cortex tenant","variables":{"tenant":{"default":"api","description":"Tenant-specific subdomain"},"region":{"default":"us","description":"Deployment region","enum":["us","eu","uk","sg","jp","ca","au","in","gov"]}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{},"schemas":{"ErrorResponse":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message describing what went wrong"},"err_extra":{"type":"object","description":"Additional error details"}},"required":["err_code","err_msg"]}}},"Error":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer","description":"Error code"},"err_msg":{"type":"string","description":"Error message"},"err_extra":{"type":"object","description":"Additional error details"}}}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/public_api/v2/compliance/categories/{category_id}":{"delete":{"operationId":"papiDeleteCategory","summary":"Delete a category (v2)","description":"Deletes a category and cascades to its subcategories and all associated controls.\nRequires `platform_compliance_edit` permission.\n\nReturns **400** if the parent standard is official (`is_custom: false`).\nOut-of-the-box standards and their children are immutable from this API.\n\n\n**Required license:** Requires the Cortex Cloud Posture Management add-on.","tags":["Categories"],"responses":{"204":{"description":"Category deleted (cascades to subcategories and controls)"},"400":{"description":"Bad request. Returned when the parent standard is official\n(`is_custom: false`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

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

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

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

```
GET https://cortex-docs.paloaltonetworks.com/xdr-5-api/compliance-controls/categories.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.