Broker VM (Tenant-Side) overview

Programmatic management of Cortex Broker VMs from the Cortex tenant side. All endpoints are served by the Cortex tenant backend at https://api-{fqdn}/public_api/v1/brokers/... and operate on brokers that have already registered with the tenant.

Use this API to:

• List brokers and inspect their configuration, applets, and metrics.
• Edit broker metadata (name, FQDN, proxy, NTP, SSH, SSL, auto-upgrade).
• Issue Broker VM registration tokens for new installations.
• Trigger broker-lifecycle actions (reboot, shutdown, upgrade).
• Configure and (de)activate applets that run on the broker.
• Request, poll, and download remote log bundles.

Companion specification

A separate direct Broker Public API is served by the Broker VM appliance itself at https://{broker_host}/public_api/v1/.... It covers initial-bootstrap auth, on-appliance network configuration, and a synchronous log-bundle stream. The two surfaces share the /public_api/v1/ URL prefix but live on different hostnames and use different authentication. See the Broker VM (On-Appliance) API reference.

Authentication

All endpoints in this spec require both:

• Authorization: <api_key> — the tenant API key value.
• x-xdr-auth-id: <api_key_id> — the tenant API key ID.

Both headers are mandatory; missing either yields 401 Unauthorized. The authenticated caller must additionally hold the broker_action permission, enforced uniformly across every endpoint in this spec.

Response envelope

All success responses return the resource directly as the response body. All error responses share a single shape:

{ "description": "<message>", "errors": [ { "field": "...", "message": "..." } ] }

The errors array is present only on validation failures (400 Bad Request).

Rate limiting

Tenant-level rate limiting is enforced by the gateway, not per-operation, and is therefore not represented in this spec.