Azure Resource Manager Deployments REST API used by Microsoft Bicep to deploy infrastructure as code templates. Provides operations for creating, validating, and managing ARM/Bicep template deployments at resource group, subscription, management group, and tenant scopes.
openapi: 3.1.0
info:
title: Microsoft Bicep Deployments API
description: >-
Azure Resource Manager Deployments REST API used by Microsoft Bicep to deploy
infrastructure as code templates. Provides operations for creating, validating,
and managing ARM/Bicep template deployments at resource group, subscription,
management group, and tenant scopes.
version: '2025-04-01'
contact:
name: Microsoft Azure Support
url: https://azure.microsoft.com/en-us/support/
license:
name: MIT
url: https://github.com/Azure/bicep/blob/main/LICENSE
termsOfService: https://azure.microsoft.com/en-us/support/legal/
externalDocs:
description: Azure Resource Manager Deployments API Documentation
url: https://learn.microsoft.com/en-us/rest/api/resources/deployments
servers:
- url: https://management.azure.com
description: Azure Resource Manager Global Endpoint
tags:
- name: Deployments
description: Create, validate, and manage ARM/Bicep template deployments
security:
- azure_auth:
- user_impersonation
paths:
? /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}
: put:
operationId: Deployments_CreateOrUpdate
summary: Microsoft Bicep Create or update a deployment
description: >-
Deploys resources to a resource group using an ARM/Bicep template.
You can provide the template directly or link to a template URI or
Template Spec.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
responses:
'200':
description: Deployment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExtended'
'201':
description: Deployment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExtended'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
get:
operationId: Deployments_Get
summary: Microsoft Bicep Get a deployment
description: Gets a deployment by name within a resource group.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
responses:
'200':
description: Deployment details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExtended'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
delete:
operationId: Deployments_Delete
summary: Microsoft Bicep Delete a deployment
description: >-
Deletes a deployment from the deployment history. Does not affect
deployed resources.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
responses:
'202':
description: Accepted - delete operation in progress
'204':
description: Deployment already deleted
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
head:
operationId: Deployments_CheckExistence
summary: Microsoft Bicep Check deployment existence
description: Checks whether a deployment exists in a resource group.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
responses:
'204':
description: Deployment exists
'404':
description: Deployment not found
? /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}/validate
: post:
operationId: Deployments_Validate
summary: Microsoft Bicep Validate a deployment template
description: >-
Validates whether the specified template is syntactically correct and
will be accepted by Azure Resource Manager. This is the primary
validation endpoint used by the Bicep CLI.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
responses:
'200':
description: Validation succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentValidateResult'
'202':
description: Accepted - validation in progress
'400':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentValidateResult'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
? /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}/cancel
: post:
operationId: Deployments_Cancel
summary: Microsoft Bicep Cancel a running deployment
description: >-
Cancels a currently running template deployment. Only deployments
in progress can be cancelled.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
responses:
'204':
description: Deployment cancelled successfully
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
? /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}/exportTemplate
: post:
operationId: Deployments_ExportTemplate
summary: Microsoft Bicep Export a deployment template
description: Exports the template used for the specified deployment.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
responses:
'200':
description: Template exported successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExportResult'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
? /subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}/whatIf
: post:
operationId: Deployments_WhatIf
summary: Microsoft Bicep Run what-if analysis
description: >-
Returns changes that will be made by the deployment if executed at the
scope of the resource group. Used by Bicep CLI what-if command.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentWhatIf'
responses:
'200':
description: What-if analysis completed
content:
application/json:
schema:
$ref: '#/components/schemas/WhatIfOperationResult'
'202':
description: Accepted - what-if analysis in progress
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments:
get:
operationId: Deployments_ListByResourceGroup
summary: Microsoft Bicep List deployments by resource group
description: Get all the deployments for a resource group.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/resourceGroupName'
- $ref: '#/components/parameters/apiVersion'
- name: $filter
in: query
description: OData filter expression to apply
schema:
type: string
- name: $top
in: query
description: Maximum number of results to return
schema:
type: integer
responses:
'200':
description: List of deployments returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentListResult'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}:
put:
operationId: Deployments_CreateOrUpdateAtSubscriptionScope
summary: Microsoft Bicep Create or update a deployment at subscription scope
description: Deploys resources at subscription scope using an ARM/Bicep template.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScopedDeployment'
responses:
'200':
description: Deployment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExtended'
'201':
description: Deployment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExtended'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
get:
operationId: Deployments_GetAtSubscriptionScope
summary: Microsoft Bicep Get a deployment at subscription scope
description: Gets a deployment at subscription scope.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
responses:
'200':
description: Deployment details returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentExtended'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}/validate:
post:
operationId: Deployments_ValidateAtSubscriptionScope
summary: Microsoft Bicep Validate a deployment at subscription scope
description: Validates a template deployment at subscription scope.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/subscriptionId'
- $ref: '#/components/parameters/deploymentName'
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScopedDeployment'
responses:
'200':
description: Validation succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentValidateResult'
'202':
description: Accepted - validation in progress
'400':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentValidateResult'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
/providers/Microsoft.Resources/calculateTemplateHash:
post:
operationId: Deployments_CalculateTemplateHash
summary: Microsoft Bicep Calculate template hash
description: Calculate the hash of the given ARM/Bicep compiled template.
tags:
- Deployments
parameters:
- $ref: '#/components/parameters/apiVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The template content to hash
responses:
'200':
description: Template hash calculated successfully
content:
application/json:
schema:
type: object
properties:
minifiedTemplate:
type: string
description: The minified template string
templateHash:
type: string
description: The hash of the template
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/CloudError'
security: []
components:
securitySchemes:
azure_auth:
type: oauth2
description: Azure Active Directory OAuth2 Flow
flows:
implicit:
authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
scopes:
user_impersonation: Impersonate your user account
parameters:
subscriptionId:
name: subscriptionId
in: path
required: true
description: The Microsoft Azure subscription ID
schema:
type: string
resourceGroupName:
name: resourceGroupName
in: path
required: true
description: >-
The name of the resource group. The name is case insensitive.
schema:
type: string
minLength: 1
maxLength: 90
pattern: ^[-\w\.\_\(\)]+$
deploymentName:
name: deploymentName
in: path
required: true
description: The name of the deployment
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[-\w\.\_\(\)]+$
apiVersion:
name: api-version
in: query
required: true
description: The API version to use for this operation
schema:
type: string
default: '2025-04-01'
schemas:
Deployment:
type: object
required:
- properties
properties:
properties:
$ref: '#/components/schemas/DeploymentProperties'
location:
type: string
description: The location to store the deployment data
tags:
type: object
additionalProperties:
type: string
description: Deployment tags
identity:
$ref: '#/components/schemas/DeploymentIdentity'
ScopedDeployment:
type: object
required:
- properties
- location
properties:
properties:
$ref: '#/components/schemas/DeploymentProperties'
location:
type: string
description: The location to store the deployment data
tags:
type: object
additionalProperties:
type: string
description: Deployment tags
identity:
$ref: '#/components/schemas/DeploymentIdentity'
DeploymentProperties:
type: object
required:
- mode
properties:
template:
type: object
description: >-
The template content. Use this when passing the compiled Bicep
template directly in the request.
templateLink:
$ref: '#/components/schemas/TemplateLink'
parameters:
type: object
additionalProperties:
$ref: '#/components/schemas/DeploymentParameter'
description: >-
Name and value pairs that define the deployment parameters for
the template.
parametersLink:
$ref: '#/components/schemas/ParametersLink'
mode:
type: string
enum:
- Incremental
- Complete
description: >-
The deployment mode. Incremental adds resources without deleting
existing ones. Complete deletes resources not in the template.
debugSetting:
type: object
properties:
detailLevel:
type: string
description: >-
Specifies the type of information to log for debugging.
Permitted values are none, requestContent, responseContent,
or both separated by a comma.
onErrorDeployment:
type: object
properties:
type:
type: string
enum:
- LastSuccessful
- SpecificDeployment
description: The deployment on error behavior type
deploymentName:
type: string
description: The deployment name to use on error
expressionEvaluationOptions:
type: object
properties:
scope:
type: string
enum:
- Outer
- Inner
- NotSpecified
description: >-
Specifies whether template expressions are evaluated within
the scope of the parent template or nested template.
validationLevel:
type: string
enum:
- Template
- Provider
- ProviderNoRbac
description: The level of validation performed on the deployment
DeploymentParameter:
type: object
properties:
value:
description: Input value to the parameter
reference:
type: object
properties:
keyVault:
type: object
properties:
id:
type: string
description: Azure Key Vault resource ID
secretName:
type: string
description: Azure Key Vault secret name
secretVersion:
type: string
description: Azure Key Vault secret version
description: Azure Key Vault parameter reference
expression:
type: string
description: Input expression to the parameter
TemplateLink:
type: object
properties:
uri:
type: string
format: uri
description: The URI of the template to deploy
id:
type: string
description: >-
The resource ID of a Template Spec. Use either the id or uri
property, but not both.
contentVersion:
type: string
description: >-
If included, must match the ContentVersion in the template.
queryString:
type: string
description: >-
The query string (for example, a SAS token) to be used with the
templateLink URI.
relativePath:
type: string
description: >-
The relativePath property can be used to deploy a linked template
at a location relative to the parent.
ParametersLink:
type: object
required:
- uri
properties:
uri:
type: string
format: uri
description: The URI of the parameters file
contentVersion:
type: string
description: >-
If included, must match the ContentVersion in the template.
DeploymentIdentity:
type: object
properties:
type:
type: string
enum:
- None
- UserAssigned
description: The identity type
userAssignedIdentities:
type: object
additionalProperties:
type: object
properties:
clientId:
type: string
format: uuid
description: The client ID of the assigned identity
principalId:
type: string
format: uuid
description: The principal ID of the assigned identity
description: The set of user assigned identities
DeploymentExtended:
type: object
properties:
id:
type: string
description: The ID of the deployment
name:
type: string
description: The name of the deployment
type:
type: string
description: The type of the deployment
location:
type: string
description: The location of the deployment
tags:
type: object
additionalProperties:
type: string
description: Deployment tags
properties:
$ref: '#/components/schemas/DeploymentPropertiesExtended'
DeploymentPropertiesExtended:
type: object
properties:
provisioningState:
type: string
enum:
- NotSpecified
- Accepted
- Running
- Ready
- Creating
- Created
- Deleting
- Deleted
- Canceled
- Failed
- Succeeded
- Updating
description: The state of provisioning
correlationId:
type: string
description: The correlation ID of the deployment
timestamp:
type: string
format: date-time
description: The timestamp of the template deployment
duration:
type: string
description: The duration of the template deployment (ISO 8601)
outputs:
type: object
description: Key/value pairs that represent deployment output
providers:
type: array
items:
$ref: '#/components/schemas/Provider'
description: The list of resource providers needed for the deployment
dependencies:
type: array
items:
$ref: '#/components/schemas/Dependency'
description: The list of deployment dependencies
templateLink:
$ref: '#/components/schemas/TemplateLink'
parameters:
type: object
description: Deployment parameters
parametersLink:
$ref: '#/components/schemas/ParametersLink'
mode:
type: string
enum:
- Incremental
- Complete
description: The deployment mode
templateHash:
type: string
description: The hash produced for the template
outputResources:
type: array
items:
$ref: '#/components/schemas/ResourceReference'
description: Array of provisioned resources
validatedResources:
type: array
items:
$ref: '#/components/schemas/ResourceReference'
description: Array of validated resources
diagnostics:
type: array
items:
$ref: '#/components/schemas/DeploymentDiagnostic'
description: Diagnostic information collected during validation
onErrorDeployment:
type: object
properties:
type:
type: string
enum:
- LastSuccessful
- SpecificDeployment
deploymentName:
type: string
provisioningState:
type: string
DeploymentValidateResult:
type: object
properties:
id:
type: string
description: The ID of the deployment
name:
type: string
description: The name of the deployment
type:
type: string
description: The type of the deployment
properties:
$ref: '#/components/schemas/DeploymentPropertiesExtended'
error:
$ref: '#/components/schemas/ErrorResponse'
DeploymentExportResult:
type: object
properties:
template:
type: object
description: The exported template content
DeploymentWhatIf:
type: object
required:
- properties
properties:
properties:
allOf:
- $ref: '#/components/schemas/DeploymentProperties'
- type: object
properties:
whatIfSettings:
type: object
properties:
resultFormat:
type: string
enum:
- ResourceIdOnly
- FullResourcePayloads
description: The format of the what-if results
location:
type: string
description: The location to store the deployment data
WhatIfOperationResult:
type: object
properties:
status:
type: string
description: Status of the what-if operation
properties:
type: object
properties:
changes:
type: array
items:
$ref: '#/components/schemas/WhatIfChange'
description: List of resource changes predicted by the what-if operation
error:
$ref: '#/components/schemas/ErrorResponse'
WhatIfChange:
type: object
properties:
resourceId:
type: string
description: Resource ID
changeType:
type: string
enum:
- Create
- Delete
- Ignore
- Deploy
- NoChange
- Modify
- Unsupported
description: Type of change to the resource
before:
type: object
description: Resource snapshot before the deployment
after:
type: object
description: Resource snapshot after the deployment
delta:
type: array
items:
type: object
properties:
path:
type: string
description: The path of the property change
propertyChangeType:
type: string
enum:
- Create
- Delete
- Modify
- Array
- NoEffect
description: The type of property change
before:
description: The value of the property before the deployment
after:
description: The value of the property after the deployment
description: The predicted changes to resource properties
DeploymentDiagnostic:
type: object
properties:
level:
type: string
enum:
- Warning
- Info
- Error
description: The diagnostic level
code:
type: string
description: The diagnostic code
message:
type: string
description: The diagnostic message
target:
type: string
description: The diagnostic target
DeploymentListResult:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/DeploymentExtended'
description: Array of deployments
nextLink:
type: string
format: uri
description: URL to get the next set of results
Provider:
type: object
properties:
namespace:
type: string
description: The namespace of the resource provider
resourceTypes:
type: array
items:
type: object
properties:
resourceType:
type: string
description: The resource type
locations:
type: array
items:
type: string
description: The locations where this resource type can be created
Dependency:
type: object
properties:
id:
type: string
description: The ID of the dependency
resourceType:
type: string
description: The dependency resource type
resourceName:
type: string
description: The dependency resource name
dependsOn:
type: array
items:
type: object
properties:
id:
type: string
resourceType:
type: string
resourceName:
type: string
description: The list of sub-dependencies
ResourceReference:
type: object
properties:
id:
type: string
description: The fully qualified Azure resource ID
resourceType:
type: string
description: The resource type
apiVersion:
type: string
description: The API version the resource was deployed with
CloudError:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorResponse'
ErrorResponse:
type: object
properties:
code:
type: string
description: The error code
message:
type: string
description: The error message
target:
type: string
description: The error target
details:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
description: The error details
additionalInfo:
type: array
items:
type: object
properties:
type:
type: string
description: The additional info type
info:
type: object
description: The additional info
description: The error additional info