> 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/xsoar-8-api/cortex-xsoar-8.x-apis/engines.md).

# Engines

APIs for managing engines

## Create an engine

> An engine is a proxy server application that is installed on a remote machine and enables communication between the remote machine and the Cortex XSOAR tenant. You can run playbooks, scripts, commands, and integrations on the remote machine and the results are returned to the tenant.\
> \
> For more information on Cortex XSOAR engines, see \[What is an engine?]\(<https://app.gitbook.com/s/AEIjuYE3RXcIfmuQnBbm/configure-cortex-xsiam/engines/what-is-an-engine>).

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines":{"post":{"summary":"Create an engine","tags":["Engines"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Engine ID"},"version":{"type":"integer","description":"Engine version"},"cacheVersn":{"type":"integer"},"sequenceNumber":{"type":"integer"},"primaryTerm":{"type":"integer"},"modified":{"type":"string"},"sizeInBytes":{"type":"integer"},"packID":{"type":"string"},"packName":{"type":"string"},"itemVersion":{"type":"string"},"fromServerVersion":{"type":"string"},"toServerVersion":{"type":"string"},"propagationLabels":{"nullable":true},"definitionId":{"type":"string"},"prevName":{"type":"string"},"isOverridable":{"type":"boolean"},"name":{"type":"string"},"allowOnTenant":{"type":"boolean"},"locked":{"type":"boolean"},"lastSeen":{"type":"string"},"firstSeen":{"type":"string"},"lastConnectedApp":{"type":"string"},"lastDisconnect":{"type":"string"},"serviceName":{"type":"string"},"host":{"type":"string"},"user":{"type":"string"},"pkgType":{"type":"string"},"pkgName":{"type":"string"},"config":{"type":"string"},"baseUrl":{"type":"string"},"engineGroup":{"type":"string"},"protocolVersion":{"type":"string"},"os":{"type":"string"},"demistoVersion":{"type":"string"},"upgradeAvailable":{"type":"boolean"},"buildVersion":{"type":"string"},"md5":{"type":"string"},"underUpgrade":{"type":"boolean"},"upgradeStartTime":{"type":"string"},"tenantNames":{"nullable":true},"workers":{"type":"integer"},"isDefault":{"type":"boolean"},"isLegacy":{"type":"boolean"},"packageFileHash":{"type":"string"},"pyramidAPIEncryptedAuthenticationHeader":{"type":"string"},"pyramidAPIEncryptedAuthenticationHeaderTenants":{"nullable":true}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Response ID"},"status":{"type":"integer","description":"Response code"},"title":{"type":"string","description":"Response title"},"detail":{"type":"string","description":"Response details"},"error":{"type":"string","description":"Error message"},"encrypted":{"type":"boolean"},"multires":{"nullable":true}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"post-xsoar-public-v1-engines","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}],"description":"An engine is a proxy server application that is installed on a remote machine and enables communication between the remote machine and the Cortex XSOAR tenant. You can run playbooks, scripts, commands, and integrations on the remote machine and the results are returned to the tenant.\n\nFor more information on Cortex XSOAR engines, see [What is an engine?](https://app.gitbook.com/s/AEIjuYE3RXcIfmuQnBbm/configure-cortex-xsiam/engines/what-is-an-engine).","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","pkgType"],"properties":{"name":{"type":"string","description":"Unique name for the engine."},"pkgType":{"enum":["shell","zip","deb","rpm","conf"],"description":"Select the installer type:\n- `shell`: For all Linux deployments, including Ubuntu and SUSE. Automatically installs Docker/Podman, downloads Docker/Podman images, enables remote engine upgrade, and allows installation of multiple engines on the same machine.\n- `zip`: For Amazon Linux 2 machines.\n- `deb`: For Ubuntu operating systems.\n- `rpm`: For RHEL operating systems.\n- `conf`: A configuration file for download. When you install one of the other options, this configuration file (d1.conf) is installed on the engine machine.\n\n**Note:** Use `deb` and `rpm` installation when shell installation is not available. You need to manually install Docker or Podman and any dependencies, including enabling IPv4 forwarding. You must also install Python (including 3.x)."},"serviceName":{"type":"string","description":"If you are using a `shell` installer type and want to enable multiple engines to run on the same machine, enter the service name for the engine. The service name will have `d1_` added as a prefix. For example, \"d1_test-engine\"."}}}}}}}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","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."}},"description":"The query result upon error."}}}}
```

## Get all engines

> Get detailed information on all of the tenant's engines, including engine names, hosts, status, and connection.\
> \
> \*\*Note:\*\* If the \`name\` returns with a "d1\_" prefix, this indicates that it is a multiple engine (more than one engine running on the same machine).

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines/get":{"get":{"summary":"Get all engines","tags":["Engines"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"cacheVersn":{"type":"integer"},"sequenceNumber":{"type":"integer"},"primaryTerm":{"type":"integer"},"modified":{"type":"string"},"sizeInBytes":{"type":"integer"},"sortValues":{"type":"array","items":{"type":"string"}},"packID":{"type":"string"},"packName":{"type":"string"},"itemVersion":{"type":"string"},"fromServerVersion":{"type":"string"},"toServerVersion":{"type":"string"},"definitionId":{"type":"string"},"prevName":{"type":"string"},"isOverridable":{"type":"boolean"},"name":{"type":"string"},"allowOnTenant":{"type":"boolean"},"locked":{"type":"boolean"},"lastSeen":{"type":"string"},"firstSeen":{"type":"string"},"lastConnectedApp":{"type":"string"},"lastDisconnect":{"type":"string"},"serviceName":{"type":"string"},"host":{"type":"string"},"user":{"type":"string"},"pkgType":{"type":"string"},"pkgName":{"type":"string"},"config":{"type":"string"},"baseUrl":{"type":"string"},"engineGroup":{"type":"string"},"protocolVersion":{"type":"string"},"os":{"type":"string"},"demistoVersion":{"type":"string"},"upgradeAvailable":{"type":"boolean"},"buildVersion":{"type":"string"},"md5":{"type":"string"},"underUpgrade":{"type":"boolean"},"upgradeStartTime":{"type":"string"},"tenantNames":{"type":"null"},"workers":{"type":"integer"},"isDefault":{"type":"boolean"},"isLegacy":{"type":"boolean"},"packageFileHash":{"type":"string"},"pyramidAPIEncryptedAuthenticationHeader":{"type":"string"},"pyramidAPIEncryptedAuthenticationHeaderTenants":{"type":"null"},"connected":{"type":"boolean"},"modules":{"type":"null"},"propagationLabels":{"type":"array","items":{"type":"string"}}}}},"total":{"type":"integer"},"pkgTypes":{"type":"array","items":{"type":"string"}},"requestedLogs":{"type":"object","properties":{}},"engineGroups":{"type":"array","items":{"type":"object","properties":{}}}}}}}}},"operationId":"get-xsoar-public-v1-engines-get","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}],"description":"Get detailed information on all of the tenant's engines, including engine names, hosts, status, and connection.\n\n**Note:** If the `name` returns with a \"d1_\" prefix, this indicates that it is a multiple engine (more than one engine running on the same machine)."}}}}
```

## Get details by engine ID

> Get detailed information on the specified engine, including engine name, host, status, and connection.\
> \
> \*\*Note:\*\* If the \`name\` returns with a "d1\_" prefix, this indicates that it is a multiple engine (more than one engine running on the same machine).

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines/get/{id}":{"get":{"summary":"Get details by engine ID","tags":["Engines"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"cacheVersn":{"type":"integer"},"sequenceNumber":{"type":"integer"},"primaryTerm":{"type":"integer"},"modified":{"type":"string"},"sizeInBytes":{"type":"integer"},"packID":{"type":"string"},"packName":{"type":"string"},"itemVersion":{"type":"string"},"fromServerVersion":{"type":"string"},"toServerVersion":{"type":"string"},"definitionId":{"type":"string"},"prevName":{"type":"string"},"isOverridable":{"type":"boolean"},"name":{"type":"string"},"allowOnTenant":{"type":"boolean"},"locked":{"type":"boolean"},"lastSeen":{"type":"string"},"firstSeen":{"type":"string"},"lastConnectedApp":{"type":"string"},"lastDisconnect":{"type":"string"},"serviceName":{"type":"string"},"host":{"type":"string"},"user":{"type":"string"},"pkgType":{"type":"string"},"pkgName":{"type":"string"},"config":{"type":"string"},"baseUrl":{"type":"string"},"engineGroup":{"type":"string"},"protocolVersion":{"type":"string"},"os":{"type":"string"},"demistoVersion":{"type":"string"},"upgradeAvailable":{"type":"boolean"},"buildVersion":{"type":"string"},"md5":{"type":"string"},"underUpgrade":{"type":"boolean"},"upgradeStartTime":{"type":"string"},"tenantNames":{"type":"null"},"workers":{"type":"integer"},"isDefault":{"type":"boolean"},"isLegacy":{"type":"boolean"},"packageFileHash":{"type":"string"},"pyramidAPIEncryptedAuthenticationHeader":{"type":"string"},"pyramidAPIEncryptedAuthenticationHeaderTenants":{"type":"null"},"connected":{"type":"boolean"},"modules":{"type":"null"}}}},"total":{"type":"integer"},"pkgTypes":{"type":"array","items":{"type":"string"}},"requestedLogs":{"type":"object","properties":{}},"engineGroups":{"type":"array","items":{"type":"object","properties":{}}}}}}}}},"operationId":"get-xsoar-public-v1-engines-get-id","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}],"description":"Get detailed information on the specified engine, including engine name, host, status, and connection.\n\n**Note:** If the `name` returns with a \"d1_\" prefix, this indicates that it is a multiple engine (more than one engine running on the same machine)."}}}}
```

## Download the engine configuration file

> Download the \`d1.conf\` file to view the attribute values. This is only supported for engines installed with a configuration file (\`"pkgType":"conf"\`).

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines/download/{id}":{"get":{"summary":"Download the engine configuration file","tags":["Engines"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"LogLevel":{"type":"string"},"LogFile":{"type":"string"},"EngineURLs":{"type":"array","items":{"type":"string"}},"AgentURLs":{"type":"null"},"BindAddress":{"type":"string"},"EngineID":{"type":"string"},"ServerPublic":{"type":"string"},"ArtifactsFolder":{"type":"string"},"TempFolder":{"type":"string"},"Server.ExternalHostName":{"type":"string"},"http.authentication.header":{"type":"string"},"python.engine.docker":{"type":"boolean"},"powershell.engine.docker":{"type":"boolean"}}}}}}},"operationId":"get-xsoar-public-v1-engines-download-ID","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}],"description":"Download the `d1.conf` file to view the attribute values. This is only supported for engines installed with a configuration file (`\"pkgType\":\"conf\"`)."}}}}
```

## Delete an engine

> Delete the engine specified by engine ID.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines/{id}":{"delete":{"summary":"Delete an engine","tags":["Engines"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"detail":{"type":"string"},"error":{"type":"string"},"encrypted":{"type":"boolean"},"multires":{"type":"null"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}},"operationId":"delete-xsoar-public-v1-engines-ID","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}],"description":"Delete the engine specified by engine ID."}}},"components":{"schemas":{"reply":{"title":"reply","type":"object","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."}},"description":"The query result upon error."}}}}
```

## Update engine configuration

> Update an engine configuration. \
> \
> See \[Configure Engines]\(<https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.5/configure-cortex-xsoar/engines/configure-engines>) for a table that describes the common properties when editing an engine configuration.\
> \
> \*\*Note:\*\* The engine must be connected to update its configuration.&#x20;

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines/config":{"post":{"summary":"Update engine configuration","tags":["Engines"],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"405":{"description":"Method Not Allowed"}},"operationId":"post-xsoar-public-v1-engines-config","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":{"id":{"type":"string","description":"Engine ID"},"data":{"type":"object","properties":{"LogLevel":{"type":"string"},"LogFile":{"type":"string"},"EngineURLs":{"type":"array","items":{"type":"string"}},"AgentURLs":{"nullable":true},"BindAddress":{"type":"string"},"EngineID":{"type":"string"},"ServerPublic":{"type":"string"},"ArtifactsFolder":{"type":"string"},"TempFolder":{"type":"string"},"Server.ExtealHostName":{"type":"string"},"http.authentication.header":{"type":"string"},"python.engine.docker":{"type":"boolean"},"powershell.engine.docker":{"type":"boolean"}}}}}}}},"description":"Update an engine configuration. \n\nSee [Configure Engines](https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.5/configure-cortex-xsoar/engines/configure-engines) for a table that describes the common properties when editing an engine configuration.\n\n**Note:** The engine must be connected to update its configuration. "}}}}
```

## Upgrade specified engines

> Whenever there is a Cortex XSOAR major version change or a change in tenant-engine protocol version, your engines require an upgrade. In the UI on the \*\*Engines\*\* page, the \`Status\` column shows those engines that require upgrades. \
> \
> Use this endpoint to upgrade engines specified by their engine ID.\
> \
> \*\*Note:\*\* The engine must be connected to be upgraded. You can only upgrade engines if you have installed the engine using the Shell installer. If you didn't install the engine using the Shell installer, you need to remove the engine and do a fresh install.

```json
{"openapi":"3.0.1","info":{"title":"Cortex XSOAR 8 API","version":"XSOAR 8 Cloud"},"tags":[{"name":"Engines","description":"APIs for managing engines"}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/xsoar/public/v1/engines/upgrade":{"post":{"summary":"Upgrade specified engines","tags":["Engines"],"responses":{},"operationId":"post-xsoar-public-v1-engines-upgrade","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}],"description":"Whenever there is a Cortex XSOAR major version change or a change in tenant-engine protocol version, your engines require an upgrade. In the UI on the **Engines** page, the `Status` column shows those engines that require upgrades. \n\nUse this endpoint to upgrade engines specified by their engine ID.\n\n**Note:** The engine must be connected to be upgraded. You can only upgrade engines if you have installed the engine using the Shell installer. If you didn't install the engine using the Shell installer, you need to remove the engine and do a fresh install.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"List of engine IDs you wish to upgrade.","items":{"type":"string"}}}}}}}}}}}
```


---

# 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/xsoar-8-api/cortex-xsoar-8.x-apis/engines.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.