> 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/cortex-platform/widgets.md).

# Widgets

APIs for managing widgets

## Get widgets

> Get widget details by filtering based on the widget title and widget creator.
> \\
>
> \
> \*\*Note:\*\* The endpoint only returns XQL widgets and not predefined widgets.
> \\
>
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.

```json
{"openapi":"3.0.0","info":{"title":"Cortex XDR Platform APIs","version":"Cortex XDR 5.2"},"tags":[{"name":"Widgets","description":"APIs for managing widgets"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/widgets/get":{"post":{"summary":"Get widgets","tags":["Widgets"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"objects_count":{"type":"integer","description":"Number of widgets returned."},"objects":{"type":"array","items":{"type":"object","properties":{"widgets_data":{"type":"array","items":{"type":"object","properties":{"widget_key":{"type":"string"},"title":{"type":"string"},"creation_time":{"type":"integer"},"description":{"type":"string","nullable":true},"data":{"type":"object","properties":{"phrase":{"type":"string"},"time_frame":{"type":"object","properties":{"relativeTime":{"type":"integer"}}},"viewOptions":{"type":"object","properties":{"type":{"type":"string"},"commands":{"type":"array","items":{"type":"object"}}}},"gridRawStorageInfo":{"type":"object","properties":{"sort":{"type":"string","nullable":true},"coldefs":{"type":"object"},"rowHeight":{"type":"string"},"columnWidth":{"type":"integer","nullable":true}}}}},"support_time_range":{"type":"boolean"},"additional_info":{"type":"object","properties":{"query_tables":{"type":"array","items":{"type":"string"}},"query_uses_library":{"type":"boolean"}}},"creator_mail":{"type":"string"},"is_public":{"type":"boolean","description":"Indicates whether the widget is public to all users (TRUE) or is restricted to specific users (FALSE)."},"is_predefined":{"type":"boolean","description":"Indicates whether the widget is a predefined widget (TRUE) or a user-created widget (FALSE)."}}}}}}},"objects_type":{"type":"string"}}}}}},"599":{"description":"Invalid field or operator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-widgets-get","description":"Get widget details by filtering based on the widget title and widget creator.\r\n\r\n**Note:** The endpoint only returns XQL widgets and not predefined widgets.\r\n\r\nYou must have **Instance Administrator** permissions to run this endpoint.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","properties":{"filters":{"type":"array","description":"An array of filter fields.","items":{"type":"object","properties":{"field":{"description":"Identifies the dashboard field the filter is matching. Filters are based on the following keywords:\r\n- `title`: Widget title.\r\n- `created_by`: Name of the user who created the widget.","enum":["title","created_by"]},"operator":{"description":"Identifies the comparison operator you want to use for this filter. Valid keywords are:\r\n`eq` / `neq`\r\n- `created_by`: String\r\n- `title`: String\r\n\r\n`IN`\r\n- `created_by`: List of strings\r\n- `title`: List of strings","enum":["EQ","NEQ","IN"]},"value":{"type":"string","description":"Value that this filter must match. The contents of this field will differ depending on the widget field that you specified for this filter:\r\n- `title`, `created_by`: String or list of strings."}}}}}}}}}}}}}},"components":{"schemas":{"reply":{"type":"object","title":"reply","description":"The query result upon error.","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}}}}}}
```

## Insert or update widgets

> Update or add the widgets retrieved by the Get widgets API.\
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.

```json
{"openapi":"3.0.0","info":{"title":"Cortex XDR Platform APIs","version":"Cortex XDR 5.2"},"tags":[{"name":"Widgets","description":"APIs for managing widgets"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/widgets/insert":{"post":{"summary":"Insert or update widgets","tags":["Widgets"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"added_objects":{"type":"array","description":"List of widget keys and titles for all widgets successfully added.","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}}}},"updated_objects":{"type":"array","description":"List of widget keys and titles for all widgets successfully updated.","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"}}}},"errors":{"type":"array","description":"List of widget keys and error messages for all widgets that failed to be added or updated.","items":{"type":"object","properties":{"key":{"type":"string"},"error":{"type":"string"}}}}}}}}}},"operationId":"post-public_api-v1-widgets-insert","description":"Update or add the widgets retrieved by the Get widgets API.\n\nYou must have **Instance Administrator** permissions to run this endpoint.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"array","items":{"type":"object","properties":{"widgets_data":{"type":"array","description":"An array of widget details as retrieved by the Get widgets API.","items":{"type":"object","properties":{"widget_key":{"type":"string"},"title":{"type":"string"},"creation_time":{"type":"integer"},"description":{"type":"string","nullable":true},"data":{"type":"object","properties":{"phrase":{"type":"string"},"time_frame":{"type":"object","properties":{"relativeTime":{"type":"integer"}}},"viewOptions":{"type":"object","properties":{"type":{"type":"string"},"commands":{"type":"array","items":{"type":"object"}}}},"gridRawStorageInfo":{"type":"object","properties":{"sort":{"type":"string","nullable":true},"coldefs":{"type":"object"},"rowHeight":{"type":"string"},"columnWidth":{"type":"integer","nullable":true}}}}},"support_time_range":{"type":"boolean"},"additional_info":{"type":"object","properties":{"query_tables":{"type":"array","items":{"type":"string"}},"query_uses_library":{"type":"boolean"}}},"creator_mail":{"type":"string"}}}}}}}}}}}}}}}}
```

## Delete widgets

> Delete the widgets retrieved by the Get widgets API.\
> \
> You must have \*\*Instance Administrator\*\* permissions to run this endpoint.

```json
{"openapi":"3.0.0","info":{"title":"Cortex XDR Platform APIs","version":"Cortex XDR 5.2"},"tags":[{"name":"Widgets","description":"APIs for managing widgets"}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/widgets/delete":{"post":{"summary":"Delete widgets","tags":["Widgets"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"objects_count":{"type":"integer","description":"Number of widgets deleted."},"objects":{"type":"array","description":"List of widget IDs of widgets successfully deleted.","items":{"type":"string"}}}}}}},"599":{"description":"Invalid field or operator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-public_api-v1-widgets-delete","description":"Delete the widgets retrieved by the Get widgets API.\n\nYou must have **Instance Administrator** permissions to run this endpoint.","parameters":[{"schema":{"type":"string"},"in":"header","name":"Authorization","description":"{api_key}","required":true},{"schema":{"type":"string"},"in":"header","name":"x-xdr-auth-id","description":"{api_key_id}","required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["request_data"],"properties":{"request_data":{"type":"object","properties":{"filters":{"type":"array","description":"An array of filter fields.","items":{"type":"object","properties":{"field":{"description":"Identifies the dashboard field the filter is matching. Filters are based on the following keywords:\r\n- `title`: Widget title.\r\n- `created_by`: Name of the user who created the widget.","enum":["created_by","title"]},"value":{"description":"Identifies the comparison operator you want to use for this filter. Valid keywords are:\r\n`EQ` / `NEQ`\r\n- `created_by`: String\r\n- `title`: String\r\n\r\n`IN`\r\n- `created_by`: List of strings\r\n- `title`: List of strings","enum":["EQ","NEQ","IN"]},"operator":{"type":"string","description":"Value that this filter must match. The contents of this field will differ depending on the widget field that you specified for this filter:\r\n- `title`, `created_by`: String or list of strings."}}}}}}}}}}}}}},"components":{"schemas":{"reply":{"type":"object","title":"reply","description":"The query result upon error.","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}}}}}}
```


---

# 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/cortex-platform/widgets.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.