Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Brokers

Manage the inventory of registered Broker VMs — list, edit, register new ones, remove, reboot, shutdown, upgrade. Endpoints in this tag operate on the broker as a whole, not on individual applets.

List registered Broker VMs

get

Return all brokers registered with the tenant, optionally filtered by one or more device_id and/or device_name values supplied in the request body.

The response is a JSON array of broker records, each carrying the broker identity (device_id, name, FQDN, version), connectivity and configuration status, resource usage (CPU, memory, disk), network configuration (interfaces, subnet, proxy, NTP), policy (auto-upgrade window, SSH access, SSL/CA certificates), and the list of currently configured applets with their per-applet status and metrics.

No pagination today — the full list is returned in a single response. Filters are applied server-side: device_id by exact match, and device_name by shell-style wildcard (fnmatch, case-insensitive when a */? wildcard is present) falling back to exact match for values without wildcards.

Filtered no-match returns null — when a filter is supplied but no broker matches, the 200 body is JSON null (not []). An unfiltered request always returns a JSON array.

Required permission: broker_action.

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Body

Optional filters for getBrokers. Omit the body entirely to return every broker.

idstring[]Optional

Exact-match filter on device_id.

namestring[]Optional

Filter on device_name. A value containing shell-style wildcards (*, ?) is matched with fnmatch (case-insensitive); a value without wildcards is matched exactly (case-sensitive). Multiple values are OR-combined.

Responses
200

Brokers matching the request. An unfiltered request returns a JSON array (possibly empty). A filtered request that matches nothing returns JSON null — hence the schema is nullable.

application/json

Full inventory record for a single registered broker.

device_idstringRequired

Unique identifier of the broker within the tenant.

device_namestringRequired

Operator-supplied display name.

statusstringRequired

Connectivity / lifecycle status of the broker (e.g., CONNECTED, DISCONNECTED, transitory states such as IMPORT_CONFIG).

versionstringRequired

Broker VM platform version (e.g., 10.2.0).

external_interfacestringRequired

IP address of the broker's externally-facing interface.

all_interfacesstring[]Required

IP addresses of every configured interface.

cluster_namestring · nullableOptional

Cluster the broker belongs to, or null if standalone.

configuration_statusstringRequired

Whether the broker's persisted configuration matches its applied configuration (e.g., Configured, Misconfigured).

cpu_usagenumber · float · nullableOptional

Recent CPU usage as a percentage (0–100), or null if unavailable.

memory_usagenumber · float · nullableOptional

Recent memory usage as a percentage (0–100), or null if unavailable.

disk_usagenumber · float · nullableOptional

Recent disk usage as a percentage (0–100), or null if unavailable.

last_seenstring · nullableOptional

ISO 8601 UTC timestamp of the broker's last sync.

Example: 2026-05-17T09:55:11+00:00
upgrade_timestring · nullableOptional

ISO 8601 UTC timestamp of the broker's last upgrade.

fqdnstringRequired

Broker's fully qualified domain name.

web_ui_listening_portstring · nullableOptional

Port the broker web UI listens on, or null.

ntp_serversstring[]Required

Configured NTP servers.

internal_network_subnetstringRequired

Broker internal subnet CIDR.

monitoringbooleanRequired

Whether monitoring metric collection is enabled.

get/public_api/v1/brokers/
GET /public_api/v1/brokers/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
[
  {
    "device_id": "6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02",
    "device_name": "broker-eu-01",
    "status": "CONNECTED",
    "version": "10.2.0",
    "external_interface": "10.0.0.42",
    "all_interfaces": [
      "10.0.0.42"
    ],
    "cluster_name": null,
    "configuration_status": "Configured",
    "cpu_usage": 7.3,
    "memory_usage": 41.2,
    "disk_usage": 23,
    "last_seen": "2026-05-17T09:55:11+00:00",
    "upgrade_time": "2026-04-30T22:10:00+00:00",
    "fqdn": "broker-eu-01.example.com",
    "proxy_server": null,
    "web_ui_listening_port": "443",
    "ntp_servers": [
      "pool.ntp.org"
    ],
    "internal_network_subnet": "172.16.0.0/24",
    "auto_upgrade": {
      "enabled": true,
      "days_in_week": [
        "Saturday",
        "Sunday"
      ],
      "schedule": "specific",
      "schedule_from": "22:00",
      "schedule_to": "02:00",
      "timezone": "UTC"
    },
    "monitoring": true,
    "ssh_access": {
      "type": "enabled",
      "welcome_message": "Authorized access only.",
      "ssh_public_keys": [
        "ssh-ed25519 AAAA...  ops@example.com"
      ]
    },
    "ssl_server_certificates": null,
    "trusted_ca_certificate": null,
    "apps": [
      {
        "name": "WEC",
        "status": "Connected"
      }
    ]
  }
]

Edit a Broker VM

post

Apply configuration changes to a single broker. Any field omitted from the request body is left unchanged. The endpoint returns an action_id for the asynchronous propagation of the change to the broker; poll getActionStatus to observe completion.

Required permission: broker_action.

Mutually-exclusive concerns

  • ssh_keys entries must start with one of ssh-rsa, ssh-ed25519, ssh-dss, ecdsa-sha2- — otherwise 400.

  • webui_port must be an integer in [1, 65535].

  • internal_network must be a valid CIDR.

  • When auto_upgrade=true and upgrade_window is provided with start_time and end_time, the window must be at least 4 hours long.

Notable error mappings

  • 404 Not Found — device_id is unknown.

  • 409 Conflict — broker is currently disconnected.

  • 403 Forbidden — broker is a cluster member (edit the cluster configuration instead).

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Path parameters
device_idstring · min: 1Required

The broker device identifier as returned by getBrokers.

Example: 6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02
Body

Patch for a single broker. Any field omitted from the body is left unchanged. Server-side validation rules are described per-field below.

namestringOptional

New display name for the broker.

fqdnstringOptional

New fully qualified domain name.

webui_portstringOptional

Port the broker's web UI listens on. Must parse as an integer in [1, 65535].

Example: 443
ntpstring[]Optional

List of NTP server hostnames or IPs.

internal_networkstringOptional

Internal network CIDR. Must parse as an IPv4 network.

Example: 172.16.0.0/24
auto_upgradebooleanOptional

Master switch for auto-upgrade. When true, upgrade_window should also be provided.

allow_monitoringbooleanOptional

Whether the broker reports monitoring metrics.

ssh_enabledbooleanOptional

Whether SSH access to the broker is enabled.

ssh_keysstring[]Optional

Authorized SSH public keys. Each entry must start with one of ssh-rsa, ssh-ed25519, ssh-dss, ecdsa-sha2-.

welcome_messagestringOptional

SSH login banner.

ssl_crtstringOptional

PEM-encoded server certificate (paired with ssl_key).

ssl_keystringOptional

PEM-encoded private key (paired with ssl_crt).

ssl_crt_file_namestringOptional

Display name for the SSL certificate file.

ssl_key_file_namestringOptional

Display name for the SSL key file.

broker_ui_passwordstring · passwordOptional

New broker web-UI admin password (write-only; never returned by getBrokers).

Responses
201

Edit accepted; poll action_id for propagation status.

application/json

Acknowledgement of an accepted edit.

action_idstringRequired

Opaque identifier of the asynchronous action; poll getActionStatus.

Example: act_2c8d6b9e1a
post/public_api/v1/brokers/{device_id}/
POST /public_api/v1/brokers/{device_id}/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "name": "broker-eu-01-prod"
}
{
  "action_id": "act_2c8d6b9e1a"
}

Remove a Broker VM from the tenant

post

Permanently de-register a broker. The broker is not uninstalled from its host; it is simply removed from the tenant's inventory and will be ignored by subsequent syncs.

Required permission: broker_action.

  • 404 Not Found — device_id is unknown.

  • 403 Forbidden — broker is a cluster member; remove it from the cluster first.

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Path parameters
device_idstring · min: 1Required

The broker device identifier as returned by getBrokers.

Example: 6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02
Responses
200

Broker removed.

application/json
objectOptional

Empty object on success.

post/public_api/v1/brokers/{device_id}/delete/
POST /public_api/v1/brokers/{device_id}/delete/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Accept: */*

{}

Generate a Broker VM registration token

post

Issue a short-lived registration token to be used by a new Broker VM during its first-time activation. The token is opaque to the caller; pass it verbatim to the appliance's direct API /public_api/v1/register endpoint (see broker-direct-papi.yaml).

Not idempotent — each call produces a new token.

Required permission: broker_action.

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Responses
200

Token issued.

application/json

Payload returned by generateRegistrationToken. The token is opaque to the caller; pass it verbatim to the broker's direct API /public_api/v1/register endpoint.

tokenstring · min: 1Required

Opaque registration token. Pass verbatim to the appliance's direct API /public_api/v1/register endpoint.

post/public_api/v1/brokers/registration_token/
POST /public_api/v1/brokers/registration_token/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Accept: */*

{
  "token": "<registration-token-opaque-32-char-string>"
}

Reboot a Broker VM

post

Request an asynchronous reboot of the broker's underlying operating system. The endpoint returns immediately once the action is enqueued; observe completion by inspecting the broker's status through getBrokers — status will cycle through reconnect states.

Required permission: broker_action.

  • 404 Not Found — device_id is unknown.

  • 409 Conflict — broker is disconnected and cannot receive the action.

The returned action_id can also be polled via getActionStatus.

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Path parameters
device_idstring · min: 1Required

The broker device identifier as returned by getBrokers.

Example: 6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02
Responses
200

Reboot accepted; poll action_id for completion status.

application/json

Acknowledgement of an accepted lifecycle action (reboot, shutdown, or upgrade).

action_idstringRequired

Opaque identifier of the asynchronous lifecycle action; poll getActionStatus.

Example: act_2c8d6b9e1a
post/public_api/v1/brokers/{device_id}/reboot/
POST /public_api/v1/brokers/{device_id}/reboot/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Accept: */*

{
  "action_id": "act_2c8d6b9e1a"
}

Shut down a Broker VM

post

Request an asynchronous shutdown of the broker. The broker becomes DISCONNECTED once the OS powers down and will require manual intervention (or hypervisor automation) to come back online.

Required permission: broker_action.

  • 404 Not Found — device_id is unknown.

  • 409 Conflict — broker is already disconnected.

The returned action_id can also be polled via getActionStatus.

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Path parameters
device_idstring · min: 1Required

The broker device identifier as returned by getBrokers.

Example: 6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02
Responses
200

Shutdown accepted; poll action_id for completion status.

application/json

Acknowledgement of an accepted lifecycle action (reboot, shutdown, or upgrade).

action_idstringRequired

Opaque identifier of the asynchronous lifecycle action; poll getActionStatus.

Example: act_2c8d6b9e1a
post/public_api/v1/brokers/{device_id}/shutdown/
POST /public_api/v1/brokers/{device_id}/shutdown/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Accept: */*

{
  "action_id": "act_2c8d6b9e1a"
}

Upgrade a Broker VM to the latest available version

post

Trigger an asynchronous upgrade of the broker to the most recent version available for its OS family. The broker will reboot one or more times during the upgrade; observe progress via getBrokers.

Required permission: broker_action.

  • 404 Not Found — device_id is unknown.

  • 409 Conflict — broker is disconnected.

The returned action_id can also be polled via getActionStatus.

Authorizations
AuthorizationstringRequired

The tenant API key value, sent as the literal Authorization header value (no Bearer prefix).

x-xdr-auth-idstringRequired

The tenant API key identifier corresponding to the value sent in Authorization.

Path parameters
device_idstring · min: 1Required

The broker device identifier as returned by getBrokers.

Example: 6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02
Responses
200

Upgrade accepted; poll action_id for completion status.

application/json

Acknowledgement of an accepted lifecycle action (reboot, shutdown, or upgrade).

action_idstringRequired

Opaque identifier of the asynchronous lifecycle action; poll getActionStatus.

Example: act_2c8d6b9e1a
post/public_api/v1/brokers/{device_id}/upgrade/
POST /public_api/v1/brokers/{device_id}/upgrade/ HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Authorization: YOUR_API_KEY
x-xdr-auth-id: YOUR_API_KEY
Accept: */*

{
  "action_id": "act_2c8d6b9e1a"
}
PreviousBroker VM (Tenant-Side) overview
NextActions

Last updated

Was this helpful?