--- type: api title: Preview a managed integrations upgrade description: **Spaces method and path for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-post-fleet-managed-integrations-upgrade-dryrun resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-post-fleet-managed-integrations-upgrade-dryrun products: - Kibana --- # Preview a managed integrations upgrade Availability: 9.5+ - Server: `https://{kibana_url}` ## Paths - `POST` `/api/fleet/managed_integrations/_upgrade/dryrun` - `POST` `/s/{space_id}/api/fleet/managed_integrations/_upgrade/dryrun` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#basicauth) ## Description Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information. Preview upgrading multiple managed integrations without applying any change. Targets the installed package version by default; pass `pkgVersion` to preview a specific (for example, not-yet-installed) version. Each result returns the current/proposed version and any migration errors, plus — only on a clean dry-run (`hasErrors: false`) — the migrated `proposedPolicy`. `proposedPolicy` is for the edit-and-upgrade flow (edit it, then save via the update (PUT) endpoint); to apply an upgrade as-is, use `_upgrade`. ## Request Body `application/json` - `pkgVersion` (string · max: 256) — optional Target package version to preview the upgrade against. Defaults to the installed package version. - `policyIds` ([] string · max: 1000) — required IDs of the managed integrations to preview upgrading. ## Responses #### `200` Indicates a successful response. Each clean item (`hasErrors: false`) previews the migrated policy as a consumable managed integration (`proposedPolicy`); a missing id, an id that is not a managed integration, or a migration error, is reported as a per-item failure (`hasErrors: true`, with `proposedPolicy` omitted) without failing the batch. Inspect every item. `application/json` Type: `[] object · max: 10000` - `body` (object) - `message` (string · max: 4096) Error message when the dry-run failed for this policy. - `currentVersion` (string · max: 256) The current installed package version of the policy. - `errors` ([] object · max: 1000) Migration errors encountered while computing the upgrade. - `message` (string · max: 4096) Human-readable migration error. - `hasErrors` (boolean) Whether the dry-run migration produced any errors. - `id` (string · max: 256) The ID of the managed integration. - `name` (string · max: 256) The name of the managed integration. - `proposedPolicy` ({}) - `additional_datastreams_permissions` ([] string · max: 1000) Additional data stream permissions granted to the managed integration. - `cloud_connector` ({}) - `cloud_connector_id` (string · max: 255) The ID of the cloud connector. - `enabled` (boolean) Whether the cloud connector is active for this policy. - `created_at` (string · max: 64) Creation timestamp (ISO 8601). - `created_by` (string · max: 1024) User who created the policy. - `description` (string · max: 2048) Managed integration description. - `global_data_tags` ([] object · max: 100) Custom data tags applied to all data produced by this policy. - `name` (string · max: 1024) The name of the custom field. - `value` (union string | number) The value of the custom field. - `id` (string · max: 255) Managed integration unique identifier. - `inputs` (map string to object) Package policy inputs. Refer to the integration documentation to know which inputs are available. Map values (object) - `condition` (string · max: 10000) — nullable Agent condition expression to evaluate whether to apply this input. - `deprecated` ({}) - `description` (string · max: 4096) - `replaced_by` (map string to string) - `since` (string · max: 50) - `enabled` (boolean) Enable or disable that input. Defaults to `true` (enabled). - `streams` (map string to object) Input streams. Refer to the integration documentation to know which streams are available. Map values (object) - `condition` (string · max: 10000) — nullable Agent condition expression to evaluate whether to apply this stream. - `deprecated` ({}) - `description` (string · max: 4096) - `replaced_by` (map string to string) - `since` (string · max: 50) - `enabled` (boolean) Enable or disable that stream. Defaults to `true` (enabled). - `var_group_selections` (map string to string) Variable group selections. Maps var_group name to the selected option name within that group. - `vars` (map string to anyOf) Input/stream level variable. Refer to the integration documentation for more information. - `vars` (map string to anyOf) Input/stream level variable. Refer to the integration documentation for more information. - `name` (string · max: 255) Managed integration name. - `namespace` (string · max: 100) Policy namespace. Defaults to the agent policy namespace. - `package` ({}) - `name` (string · max: 255) Integration package name. - `title` (string · max: 255) Integration package display title. - `version` (string · max: 50) Integration package version. - `updated_at` (string · max: 64) Last update timestamp (ISO 8601). - `updated_by` (string · max: 1024) User who last updated the policy. - `var_group_selections` (map string to string) Variable group selections. Maps var_group name to the selected option name within that group. - `vars` (map string to anyOf) Input/stream level variable. Refer to the integration documentation for more information. - `proposedVersion` (string · max: 256) The package version the policy would be upgraded to. - `statusCode` (number) HTTP-like status code when the dry-run failed for this policy. #### `400` Bad Request `application/json` - `attributes` (object) - `error` (string) - `errorType` (string) - `message` (string) - `statusCode` (number) ## Code Examples #### Console ```console POST /api/fleet/managed_integrations/_upgrade/dryrun { "policyIds": [ "d52a7812-5736-4fdc-aed8-72152afa1ffa" ] } ``` #### curl ```curl curl -X POST "https://{kibana_url}/api/fleet/managed_integrations/_upgrade/dryrun" \ -H "kbn-xsrf: true" \ -H "Content-Type: application/json" \ -d '{ "policyIds": [ "d52a7812-5736-4fdc-aed8-72152afa1ffa" ] }' ``` ## Response Examples #### Upgrade managed integrations dry run migration errors Example dry-run response where migrating the config to the new version produced errors. `hasErrors` is true and `errors` explains why; do not feed the (partial) proposed config into the update endpoint without resolving them. ```json [ { "currentVersion": "1.5.0", "errors": [ { "message": "Variable \u0022organization_id\u0022 is required" } ], "hasErrors": true, "id": "d52a7812-5736-4fdc-aed8-72152afa1ffa", "name": "ess_billing-1", "proposedVersion": "1.6.0" } ] ``` #### Upgrade managed integrations dry run mixed response Example dry-run response for a mixed batch: one managed integration previews cleanly while two ids are missing or not managed integrations. Ids that are missing or not managed integrations are surfaced as per-item failures (`hasErrors: true` + `statusCode`) without failing the batch, and results stay in request order. ```json [ { "currentVersion": "0.5.0", "hasErrors": false, "id": "2e426392-f856-4ab2-bc31-92d4dbb8d134", "name": "agentless_hello_world-16", "proposedPolicy": { "cloud_connector": "null", "created_at": "2026-07-01T15:59:08.299Z", "created_by": "admin", "description": "", "id": "2e426392-f856-4ab2-bc31-92d4dbb8d134", "inputs": { "agentless_hello_world-cel": { "enabled": true, "streams": { "agentless_hello_world.generic": { "enabled": true, "vars": { "url": "https://epr.elastic.co" } }, "agentless_hello_world.mock_counter": { "enabled": false, "vars": { "events_per_second": 10, "mode": "constant", "spike_events": 100, "spike_every_seconds": 60 } } } }, "agentless_hello_world-httpjson": { "enabled": false, "streams": { "agentless_hello_world.generic": { "enabled": false, "vars": { "url": "https://epr.elastic.co" } } } } }, "name": "agentless_hello_world-16", "namespace": "default", "package": { "name": "agentless_hello_world", "title": "Agentless Hello World", "version": "0.5.0" }, "updated_at": "2026-07-01T16:02:14.067Z", "updated_by": "admin" }, "proposedVersion": "0.5.0" }, { "body": { "message": "Agentless policy 9300464c-6cfc-4566-850d-e9e7927457fe not found" }, "hasErrors": true, "id": "9300464c-6cfc-4566-850d-e9e7927457fe", "statusCode": 404 }, { "body": { "message": "Agentless policy 5b8763e9-791a-4038-be29-b384d578200e not found" }, "hasErrors": true, "id": "5b8763e9-791a-4038-be29-b384d578200e", "statusCode": 404 } ] ``` #### Upgrade managed integrations dry run response Example clean dry-run response (`hasErrors: false`) with the proposed (migrated) policy. `proposedPolicy` is intended for the edit-and-upgrade flow: edit it and submit the edited payload to the update (PUT) endpoint. To apply without edits, use the `_upgrade` endpoint instead. ```json [ { "currentVersion": "1.5.0", "hasErrors": false, "id": "d52a7812-5736-4fdc-aed8-72152afa1ffa", "name": "ess_billing-1", "proposedPolicy": { "created_at": "2025-11-06T18:27:43.541Z", "created_by": "test_user", "description": "test", "id": "d52a7812-5736-4fdc-aed8-72152afa1ffa", "inputs": { "ESS Billing-cel": { "enabled": true, "vars": { "organization_id": "1234" } } }, "name": "ess_billing-1", "namespace": "default", "package": { "name": "ess_billing", "title": "Elasticsearch Service Billing", "version": "1.6.0" }, "updated_at": "2025-11-06T18:27:43.541Z", "updated_by": "test_user" }, "proposedVersion": "1.6.0" } ] ``` #### Generic error response Example of a generic error response ```json { "error": "Bad Request", "message": "An error message describing what went wrong", "statusCode": 400 } ```