> 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/identity-and-access-management-iam/models.md).

# Models

## The Role object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"Role":{"type":"object","properties":{"role_id":{"type":"string","description":"The unique identifier for the role"},"pretty_name":{"type":"string","description":"The display name for the role"},"description":{"type":"string","description":"A description of the role's purpose and permissions","nullable":true},"is_custom":{"type":"boolean","description":"Indicates if the role is a custom role (true) or a predefined system role (false)"},"created_by":{"type":"string","description":"The user or system that created the role"},"created_ts":{"type":"integer","description":"The timestamp when the role was created","nullable":true},"updated_ts":{"type":"integer","description":"The timestamp when the role was last updated","nullable":true}},"required":["role_id","pretty_name","description","is_custom","created_by","created_ts","updated_ts"]}}}}
```

## The RoleCreateRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"RoleCreateRequest":{"type":"object","description":"Request object for creating a new role","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data required to create a new role","required":["component_permissions","pretty_name"],"properties":{"component_permissions":{"type":"array","items":{"type":"string"},"description":"List of component permissions for the role. Possible values can be found by using the permission configs API and referring to the `rbac_permissions` field.","minItems":1},"dataset_permissions":{"type":"array","items":{"type":"object"},"description":"Optional list of dataset permissions. This must be a list of JSONs. The layout for this JSON can be found under the 'DatasetPermission' schema . Note: possible dataset values can be found by using the permission configs API and referring to the `datasetGroups` field.","nullable":true},"pretty_name":{"type":"string","description":"Name of the role","minLength":1},"description":{"type":"string","description":"Optional description of the role","nullable":true}}}},"additionalProperties":false}}}}
```

## The UserGroupCreateRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"UserGroupCreateRequest":{"type":"object","description":"Request object for creating a new user group","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data required to create a new user group","required":["group_name"],"properties":{"group_name":{"type":"string","description":"The unique name for the user group","minLength":1},"role_id":{"type":"string","description":"The unique identifier of the role to assign to this group","nullable":true},"description":{"type":"string","description":"A brief description of the user group's purpose","nullable":true},"users":{"type":"array","items":{"type":"string"},"description":"A list of user email addresses to add to the group","nullable":true},"nested_group_ids":{"type":"array","items":{"type":"string"},"description":"A list of unique identifiers for groups to be nested within this group","nullable":true},"idp_groups":{"type":"array","items":{"type":"string"},"description":"A list of identity provider (IdP) group names to associate with this group","nullable":true}}}},"additionalProperties":false}}}}
```

## The UserGroupEditRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"UserGroupEditRequest":{"type":"object","description":"Request object for editing an existing user group","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data fields to update for the user group","properties":{"group_name":{"type":"string","description":"The new name for the user group","nullable":true},"role_id":{"type":"string","description":"The unique identifier of the new role to assign to this group","nullable":true},"description":{"type":"string","description":"The updated description for the user group","nullable":true},"users":{"type":"array","items":{"type":"string"},"description":"The updated list of user email addresses for the group","nullable":true},"nested_group_ids":{"type":"array","items":{"type":"string"},"description":"The updated list of nested group identifiers","nullable":true},"idp_groups":{"type":"array","items":{"type":"string"},"description":"The updated list of associated identity provider (IdP) group names","nullable":true}}}},"additionalProperties":false}}}}
```

## The ScopeEditRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"ScopeEditRequest":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","description":"Scope configuration data to update","properties":{"assets":{"$ref":"#/components/schemas/AssetsScopeRequest"},"datasets_rows":{"$ref":"#/components/schemas/DatasetsRowsScope"},"endpoints":{"$ref":"#/components/schemas/EndpointsScopeRequest"},"cases_issues":{"$ref":"#/components/schemas/CasesIssuesScopeRequest"}}}},"additionalProperties":false},"AssetsScopeRequest":{"type":"object","description":"Asset scope configuration for request payloads","properties":{"mode":{"type":"string","description":"Access mode for assets. Use 'scope' to limit access to specific asset groups, 'see_all' for full access, or 'no_scope' for no access","enum":["no_scope","see_all","scope"]},"asset_group_ids":{"type":"array","description":"List of asset group IDs when configuring scope (used in PUT requests)","items":{"type":"integer"}}}},"DatasetsRowsScope":{"type":"object","description":"Dataset rows scope configuration for row-level data access filtering. Only available on XSIAM tenants with the dataset scope feature enabled. When the feature is enabled, this field is mandatory in scope edit requests.","properties":{"default_filter_mode":{"type":"string","description":"Default behavior for datasets not explicitly listed in filters. 'no_scope' means no access to unlisted datasets, 'see_all' means full access to unlisted datasets","enum":["no_scope","see_all"]},"filters":{"type":"array","description":"List of dataset-specific filters to apply row-level access control","items":{"$ref":"#/components/schemas/DatasetFilter"}}}},"DatasetFilter":{"type":"object","description":"Row-level filter for a specific dataset","required":["dataset","filter"],"properties":{"dataset":{"type":"string","description":"Name of the dataset to apply the filter to"},"filter":{"type":"string","description":"Filter expression to limit data access (e.g., '_collector_name = collector_1')"}}},"EndpointsScopeRequest":{"type":"object","description":"Endpoint scope configuration for request payloads","properties":{"endpoint_groups":{"$ref":"#/components/schemas/EndpointGroupsScopeRequest"},"endpoint_tags":{"$ref":"#/components/schemas/EndpointTagsScopeRequest"}}},"EndpointGroupsScopeRequest":{"type":"object","description":"Endpoint groups scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for endpoint groups","enum":["no_scope","see_all","scope","any"]},"names":{"type":"array","description":"List of endpoint group names when configuring scope","items":{"type":"string"}}}},"EndpointTagsScopeRequest":{"type":"object","description":"Endpoint tags scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for endpoint tags","enum":["no_scope","see_all","scope","any"]},"names":{"type":"array","description":"List of endpoint tag names when configuring scope","items":{"type":"string"}}}},"CasesIssuesScopeRequest":{"type":"object","description":"Cases and issues scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for cases and issues","enum":["no_scope","see_all","scope"]},"include_cases_issues_empty_entities":{"type":"boolean","description":"Whether to include cases and issues that have no associated entities/tags"},"names":{"type":"array","description":"List of tag names when configuring scope","items":{"type":"string"}}}}}}}
```

## The AssetsScope object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"AssetsScope":{"type":"object","description":"Asset scope configuration defining access to asset groups","properties":{"mode":{"type":"string","description":"Access mode for assets. Use 'scope' to limit access to specific asset groups, 'see_all' for full access, or 'no_scope' for no access","enum":["no_scope","see_all","scope"]},"asset_groups":{"type":"array","description":"List of asset groups when mode is 'scope'","items":{"$ref":"#/components/schemas/AssetGroup"}}}},"AssetGroup":{"type":"object","description":"Asset group information","properties":{"asset_group_id":{"type":"integer","description":"Unique identifier of the asset group"},"asset_group_name":{"type":"string","description":"Display name of the asset group"}}}}}}
```

## The AssetGroup object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"AssetGroup":{"type":"object","description":"Asset group information","properties":{"asset_group_id":{"type":"integer","description":"Unique identifier of the asset group"},"asset_group_name":{"type":"string","description":"Display name of the asset group"}}}}}}
```

## The AssetsScopeRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"AssetsScopeRequest":{"type":"object","description":"Asset scope configuration for request payloads","properties":{"mode":{"type":"string","description":"Access mode for assets. Use 'scope' to limit access to specific asset groups, 'see_all' for full access, or 'no_scope' for no access","enum":["no_scope","see_all","scope"]},"asset_group_ids":{"type":"array","description":"List of asset group IDs when configuring scope (used in PUT requests)","items":{"type":"integer"}}}}}}}
```

## The DatasetsRowsScope object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"DatasetsRowsScope":{"type":"object","description":"Dataset rows scope configuration for row-level data access filtering. Only available on XSIAM tenants with the dataset scope feature enabled. When the feature is enabled, this field is mandatory in scope edit requests.","properties":{"default_filter_mode":{"type":"string","description":"Default behavior for datasets not explicitly listed in filters. 'no_scope' means no access to unlisted datasets, 'see_all' means full access to unlisted datasets","enum":["no_scope","see_all"]},"filters":{"type":"array","description":"List of dataset-specific filters to apply row-level access control","items":{"$ref":"#/components/schemas/DatasetFilter"}}}},"DatasetFilter":{"type":"object","description":"Row-level filter for a specific dataset","required":["dataset","filter"],"properties":{"dataset":{"type":"string","description":"Name of the dataset to apply the filter to"},"filter":{"type":"string","description":"Filter expression to limit data access (e.g., '_collector_name = collector_1')"}}}}}}
```

## The DatasetFilter object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"DatasetFilter":{"type":"object","description":"Row-level filter for a specific dataset","required":["dataset","filter"],"properties":{"dataset":{"type":"string","description":"Name of the dataset to apply the filter to"},"filter":{"type":"string","description":"Filter expression to limit data access (e.g., '_collector_name = collector_1')"}}}}}}
```

## The EndpointsScope object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EndpointsScope":{"type":"object","description":"Endpoint scope configuration for endpoint access control","properties":{"endpoint_groups":{"$ref":"#/components/schemas/EndpointGroupsScope"},"endpoint_tags":{"$ref":"#/components/schemas/EndpointTagsScope"}}},"EndpointGroupsScope":{"type":"object","description":"Endpoint groups scope configuration","properties":{"mode":{"type":"string","description":"Access mode for endpoint groups. 'scope' limits access to specified groups, 'see_all' grants full access, 'no_scope' denies access, 'any' grants access to any tagged endpoints","enum":["no_scope","see_all","scope","any"]},"tags":{"type":"array","description":"List of endpoint group tags when mode is 'scope'","items":{"$ref":"#/components/schemas/Tag"}},"names":{"type":"array","description":"List of endpoint group names when configuring scope (used in requests)","items":{"type":"string"}}}},"Tag":{"type":"object","description":"Tag information for scope configuration","properties":{"tag_id":{"type":"string","description":"Unique identifier of the tag (null for special tags like 'Any')","nullable":true},"tag_name":{"type":"string","description":"Display name of the tag"}}},"EndpointTagsScope":{"type":"object","description":"Endpoint tags scope configuration","properties":{"mode":{"type":"string","description":"Access mode for endpoint tags. 'scope' limits access to specified tags, 'see_all' grants full access, 'no_scope' denies access, 'any' grants access to any tagged endpoints","enum":["no_scope","see_all","scope","any"]},"tags":{"type":"array","description":"List of endpoint tags when mode is 'scope'","items":{"$ref":"#/components/schemas/Tag"}},"names":{"type":"array","description":"List of endpoint tag names when configuring scope (used in requests)","items":{"type":"string"}}}}}}}
```

## The EndpointGroupsScope object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EndpointGroupsScope":{"type":"object","description":"Endpoint groups scope configuration","properties":{"mode":{"type":"string","description":"Access mode for endpoint groups. 'scope' limits access to specified groups, 'see_all' grants full access, 'no_scope' denies access, 'any' grants access to any tagged endpoints","enum":["no_scope","see_all","scope","any"]},"tags":{"type":"array","description":"List of endpoint group tags when mode is 'scope'","items":{"$ref":"#/components/schemas/Tag"}},"names":{"type":"array","description":"List of endpoint group names when configuring scope (used in requests)","items":{"type":"string"}}}},"Tag":{"type":"object","description":"Tag information for scope configuration","properties":{"tag_id":{"type":"string","description":"Unique identifier of the tag (null for special tags like 'Any')","nullable":true},"tag_name":{"type":"string","description":"Display name of the tag"}}}}}}
```

## The EndpointTagsScope object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EndpointTagsScope":{"type":"object","description":"Endpoint tags scope configuration","properties":{"mode":{"type":"string","description":"Access mode for endpoint tags. 'scope' limits access to specified tags, 'see_all' grants full access, 'no_scope' denies access, 'any' grants access to any tagged endpoints","enum":["no_scope","see_all","scope","any"]},"tags":{"type":"array","description":"List of endpoint tags when mode is 'scope'","items":{"$ref":"#/components/schemas/Tag"}},"names":{"type":"array","description":"List of endpoint tag names when configuring scope (used in requests)","items":{"type":"string"}}}},"Tag":{"type":"object","description":"Tag information for scope configuration","properties":{"tag_id":{"type":"string","description":"Unique identifier of the tag (null for special tags like 'Any')","nullable":true},"tag_name":{"type":"string","description":"Display name of the tag"}}}}}}
```

## The CasesIssuesScope object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"CasesIssuesScope":{"type":"object","description":"Cases and issues scope configuration","properties":{"mode":{"type":"string","description":"Access mode for cases and issues. 'scope' limits access to specified tags, 'see_all' grants full access, 'no_scope' denies access","enum":["no_scope","see_all","scope"]},"include_cases_issues_empty_entities":{"type":"boolean","description":"Whether to include cases and issues that have no associated entities/tags"},"tags":{"type":"array","description":"List of case/issue tags when mode is 'scope'","items":{"$ref":"#/components/schemas/Tag"}},"names":{"type":"array","description":"List of tag names when configuring scope (used in requests)","items":{"type":"string"}}}},"Tag":{"type":"object","description":"Tag information for scope configuration","properties":{"tag_id":{"type":"string","description":"Unique identifier of the tag (null for special tags like 'Any')","nullable":true},"tag_name":{"type":"string","description":"Display name of the tag"}}}}}}
```

## The EndpointsScopeRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EndpointsScopeRequest":{"type":"object","description":"Endpoint scope configuration for request payloads","properties":{"endpoint_groups":{"$ref":"#/components/schemas/EndpointGroupsScopeRequest"},"endpoint_tags":{"$ref":"#/components/schemas/EndpointTagsScopeRequest"}}},"EndpointGroupsScopeRequest":{"type":"object","description":"Endpoint groups scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for endpoint groups","enum":["no_scope","see_all","scope","any"]},"names":{"type":"array","description":"List of endpoint group names when configuring scope","items":{"type":"string"}}}},"EndpointTagsScopeRequest":{"type":"object","description":"Endpoint tags scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for endpoint tags","enum":["no_scope","see_all","scope","any"]},"names":{"type":"array","description":"List of endpoint tag names when configuring scope","items":{"type":"string"}}}}}}}
```

## The EndpointGroupsScopeRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EndpointGroupsScopeRequest":{"type":"object","description":"Endpoint groups scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for endpoint groups","enum":["no_scope","see_all","scope","any"]},"names":{"type":"array","description":"List of endpoint group names when configuring scope","items":{"type":"string"}}}}}}}
```

## The EndpointTagsScopeRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EndpointTagsScopeRequest":{"type":"object","description":"Endpoint tags scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for endpoint tags","enum":["no_scope","see_all","scope","any"]},"names":{"type":"array","description":"List of endpoint tag names when configuring scope","items":{"type":"string"}}}}}}}
```

## The CasesIssuesScopeRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"CasesIssuesScopeRequest":{"type":"object","description":"Cases and issues scope configuration for requests","properties":{"mode":{"type":"string","description":"Access mode for cases and issues","enum":["no_scope","see_all","scope"]},"include_cases_issues_empty_entities":{"type":"boolean","description":"Whether to include cases and issues that have no associated entities/tags"},"names":{"type":"array","description":"List of tag names when configuring scope","items":{"type":"string"}}}}}}}
```

## The Tag object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"Tag":{"type":"object","description":"Tag information for scope configuration","properties":{"tag_id":{"type":"string","description":"Unique identifier of the tag (null for special tags like 'Any')","nullable":true},"tag_name":{"type":"string","description":"Display name of the tag"}}}}}}
```

## The UserEditRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"UserEditRequest":{"type":"object","description":"Request object for editing an existing user","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data fields to update for the user","properties":{"user_first_name":{"type":"string","description":"The user's first name","nullable":true},"user_last_name":{"type":"string","description":"The user's last name","nullable":true},"role_id":{"type":"string","description":"The unique identifier of the role to assign to the user. Use an empty string to remove the role.","nullable":true},"phone_number":{"type":"string","description":"The user's contact phone number","nullable":true},"status":{"type":"string","description":"The user's account status (e.g., 'Active', 'Disabled')","nullable":true},"is_hidden":{"type":"boolean","description":"Whether the user should be hidden from certain UI views","nullable":true},"user_groups":{"type":"array","items":{"type":"string"},"description":"A list of unique identifiers for the groups the user belongs to. Use an empty list to remove all group associations.","nullable":true}}}},"additionalProperties":false}}}}
```

## The ApiKeyEditRequest object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"ApiKeyEditRequest":{"type":"object","description":"Request object for editing an existing API key","required":["request_data"],"properties":{"request_data":{"type":"object","description":"The data fields to update for the API key","required":["roles","security_level"],"properties":{"roles":{"type":"array","items":{"type":"string"},"description":"A list of unique role identifiers to assign to the API key"},"security_level":{"type":"string","description":"The security level for the API key (e.g., 'standard', 'advanced')","enum":["standard","advanced"]},"comment":{"type":"string","description":"An optional comment or description for the API key","nullable":true}}}},"additionalProperties":false}}}}
```

## The DatasetPermission object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"DatasetPermission":{"type":"object","required":["category"],"properties":{"category":{"type":"string","description":"The dataset category name. Possible values can be found in the permission configs response."},"access_all":{"type":"boolean","description":"If this flag is enabled, it grants access to all datasets associated with the specified category.","nullable":true},"permissions":{"type":"array","items":{"type":"string"},"description":"This field should contain specific names of datasets under this category that the role will have access to.","nullable":true}},"additionalProperties":false}}}}
```

## The GroupType object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"GroupType":{"type":"string","description":"The type of group - Possible values: custom (Refers to a user group that is created directly on the UI), ad_type (Refers to a user group that is imported and synchronized from Azure Active Directory)","enum":["custom","ad_type"]}}}}
```

## The SecurityLevel object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"SecurityLevel":{"type":"string","description":"The chosen security level - Possible values: standard (Refers to 'standard' security level that is offered from the UI when creating an API key), Advanced (Refers to 'advanced' security level that is offered from the UI when creating an API key)","enum":["standard","advanced"]}}}}
```

## The EntityType object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"EntityType":{"type":"string","description":"The type of entity - Possible values: user (Signifies that the entity is a user), usergroup (Signifies that the entity is a custom or AD user group), apikey (Signifies that the entity is an API key)","enum":["user","user-group","api-key"]}}}}
```

## The ModeType object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"ModeType":{"type":"string","description":"The type of mode - Possible values: no_scope (Signifies no access to resources under a domain), see_all (Signifies full access to resources under a domain), scope (Signifies access only to the resources provided under the 'names' field for a domain), any (Signifies full access to resources with any tags for a domain. It is only allowed for 'endpoint_groups' and 'endpoint_tags'). Note: Datasets can only take 'no_scope' or 'see_all' values for the 'default_mode' attribute. For datasets, 'default_mode' signifies the default behavior for the datasets not present in the dataset filter list. ","enum":["no_scope","see_all","scope","any"]}}}}
```

## The Metadata object

```json
{"openapi":"3.0.2","info":{"title":"Cortex Platform IAM APIs","version":"Cortex XSIAM 3.5"},"components":{"schemas":{"Metadata":{"type":"object","description":"Metadata for the response","additionalProperties":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/identity-and-access-management-iam/models.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.