---
title: "Create a configuration deployment"
method: POST
path: "/api/v2/fleet/deployments/configure"
tags: ["Fleet Automation"]
---

# Create a configuration deployment

`POST /api/v2/fleet/deployments/configure`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/fleet/deployments/configure`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/fleet/deployments/configure/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new deployment to apply configuration changes
to a fleet of hosts matching the specified filter query.

This endpoint supports two types of configuration operations:
- `merge-patch`: Merges the provided patch data with the existing configuration file,
  creating the file if it doesn't exist.
- `delete`: Removes the specified configuration file from the target hosts.

You can optionally use `target_packages` to apply the configuration change only to specific package versions.

The deployment is created and started automatically. You can specify multiple configuration
operations to execute in order on each target host. Use the filter query to target
specific hosts using the Datadog query syntax.

Set `dry_run` to `true` to validate the configuration and resolve target hosts and packages without deploying anything. A dry run returns a 200 with the validation result instead of creating and starting a deployment.

Returns a 400 if `filter_query` or `config_operations` is missing, a target package is missing a name or version or cannot be resolved, the configuration fails validation, or the filter query does not match any host eligible for the deployment.

## Request body

- FleetDeploymentConfigureV2CreateRequest: Request payload for creating a new v2 configuration deployment.
  - `data` FleetDeploymentConfigureV2Create, required: Data for creating a new v2 configuration deployment.
    - `attributes` FleetDeploymentConfigureV2Attributes, required: Attributes for creating a new v2 configuration deployment.
      - `config_operations` FleetDeploymentOperation[], required: Ordered list of configuration file operations to perform on the target hosts.
        - `file_op` 'merge-patch' | 'delete', required: Type of file operation to perform on the target configuration file. - `merge-patch`: Merges the provided patch data with the existing configuration file. Creates the file if it doesn't exist. - `delete`: Removes the specified configuration file from the target hosts.
        - `file_path` string, required: Absolute path to the target configuration file on the host.
        - `patch` object: Patch data in JSON format to apply to the configuration file. When using `merge-patch`, this object is merged with the existing configuration, allowing you to add, update, or override specific fields without replacing the entire file. The structure must match the target configuration file format (for example, YAML structure for Datadog Agent config). Not applicable when using the `delete` operation.
      - `dry_run` boolean: Set to `true` to validate the configuration and resolve target hosts and packages without deploying anything. Returns a 200 with the validation result instead of creating and starting a real deployment.
      - `filter_query` string, required: Query used to filter and select target hosts for the deployment. Uses the Datadog query syntax.
      - `target_packages` FleetDeploymentConfigureV2Package[]: List of packages and their target versions to additionally deploy alongside the configuration change.
        - `apm_instrumentation` string: APM auto-instrumentation mode to enable for this package, if applicable.
        - `name` string, required: The name of the package to deploy.
        - `version` string, required: The target version of the package to deploy.
    - `type` 'deployment', required: The type of deployment resource.

## Response `200`

OK

- FleetDeploymentConfigureV2DryRunResponse: Response containing the result of a configuration deployment dry run.
  - `data` FleetDeploymentConfigureV2DryRun, required: The result of a configuration deployment dry run.
    - `attributes` FleetDeploymentConfigureV2DryRunAttributes, required: Attributes of a configuration deployment dry-run response.
      - `dry_run` FleetDeploymentConfigureV2DryRunResult: Validation result of a configuration deployment dry run.
        - `config_validated` boolean: Whether the configuration passed schema validation.
        - `non_upgradable_by_reason` object: Breakdown of ineligible host counts by reason. Only includes reasons with a non-zero count. Absent from the response when no targeted host is ineligible.
        - `non_upgradable_hosts` integer: Number of targeted hosts that are not eligible to receive this configuration.
      - `query` string: Query used to filter and select target hosts for the deployment.
      - `total_hosts` integer: Total number of hosts targeted by this deployment.
    - `id` string, required: Always `"dry-run"` for a dry-run response. Does not identify a real deployment and cannot be used to fetch a deployment by ID.
    - `type` 'deployment', required: The type of deployment resource.

## Other responses

- `201`: CREATED
- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)