Dev Boxes - Create Dev Box

Reference

Service:: Dev Center

API Version:: 2025-02-01

Creates or replaces a Dev Box.

PUT {endpoint}/projects/{projectName}/users/{userId}/devboxes/{devBoxName}?api-version=2025-02-01

URI Parameters

Name	In	Required	Type	Description
devBoxName	path	True	string	The name of a Dev Box. Regex pattern: `^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$`
endpoint	path	True	string uri	The DevCenter-specific URI to operate on.
projectName	path	True	string	The DevCenter Project upon which to execute operations. Regex pattern: `^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$`
userId	path	True	string	The AAD object id of the user. If value is 'me', the identity is taken from the authentication context. Regex pattern: `^[a-zA-Z0-9]{8}-([a-zA-Z0-9]{4}-){3}[a-zA-Z0-9]{12}$\|^me$`
api-version	query	True	string	The API version to use for this operation.

Request Body

Name	Required	Type	Description
poolName	True	string	The name of the Dev Box pool this machine belongs to.

Responses

Name	Type	Description
200 OK	DevBox	The request has succeeded.
201 Created	DevBox	The request has succeeded and a new resource has been created as a result. Headers Location: string Operation-Location: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

DevBox

The request has succeeded.

201 Created

DevBox

The request has succeeded and a new resource has been created as a result.

Headers

Location: string
Operation-Location: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://devcenter.azure.com/.default

Examples

Creates or replaces a Dev Box.

Sample request

HTTP

PUT https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/me/devboxes/MyDevBox?api-version=2025-02-01

{
  "poolName": "LargeDevWorkStationPool"
}

Sample response

Status code:: 200

{
  "uri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox",
  "name": "MyDevBox",
  "provisioningState": "Succeeded",
  "projectName": "ContosoProject",
  "poolName": "LargeDevWorkStationPool",
  "location": "centralus",
  "osType": "Windows",
  "user": "b08e39b4-2ac6-4465-a35e-48322efb0f98",
  "hardwareProfile": {
    "vCPUs": 8,
    "memoryGB": 32
  },
  "storageProfile": {
    "osDisk": {
      "diskSizeGB": 1024
    }
  },
  "hibernateSupport": "Enabled",
  "imageReference": {
    "name": "DevImage",
    "version": "1.0.0",
    "publishedDate": "2022-03-01T00:13:23.323Z"
  }
}

Status code:: 201

Location: https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0
Operation-Location: https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/operationstatuses/786a823c-8037-48ab-89b8-8599901e67d0

{
  "uri": "https://8a40af38-3b4c-4672-a6a4-5e964b1870ed-contosodevcenter.centralus.devcenter.azure.com/projects/myProject/users/b08e39b4-2ac6-4465-a35e-48322efb0f98/devboxes/MyDevBox",
  "name": "MyDevBox",
  "provisioningState": "Creating",
  "projectName": "ContosoProject",
  "poolName": "LargeDevWorkStationPool",
  "location": "centralus",
  "osType": "Windows",
  "user": "b08e39b4-2ac6-4465-a35e-48322efb0f98",
  "hardwareProfile": {
    "vCPUs": 8,
    "memoryGB": 32
  },
  "storageProfile": {
    "osDisk": {
      "diskSizeGB": 1024
    }
  },
  "hibernateSupport": "Enabled",
  "imageReference": {
    "name": "DevImage",
    "version": "1.0.0",
    "publishedDate": "2022-03-01T00:13:23.323Z"
  }
}

Definitions

Name	Description
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
DevBox	A Dev Box.
DevBoxProvisioningState	Indicates the provisioning state of the Dev Box.
HardwareProfile	Hardware specifications for the Dev Box.
HibernateSupport	Indicates whether hibernate is supported and enabled, disabled, or unsupported by the operating system. Unknown hibernate support is represented as null.
ImageReference	Specifies information about the image used.
LocalAdminStatus	Indicates whether owners of Dev Boxes in a pool are local administrators on the Dev Boxes.
OsDisk	Settings for the operating system disk.
OsType	The operating system type.
PowerState	The power states of a Dev Box.
SkuName	Indicates the Dev Box compute.
StorageProfile	Storage settings for the Dev Box's disks.

Azure.Core.Foundations.Error

Object

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

DevBox

Object

A Dev Box.

Name	Type	Description
actionState	string	The current action state of the Dev Box. This is state is based on previous action performed by user.
createdTime	string	Creation time of this Dev Box, in RFC3339 format.
error	Azure.Core.Foundations.Error	Provisioning or action error details. Populated only for error states.
hardwareProfile	HardwareProfile	Information about the Dev Box's hardware resources.
hibernateSupport	HibernateSupport	Indicates whether hibernate is enabled/disabled or unknown.
imageReference	ImageReference	Information about the image used for this Dev Box.
lastConnectedTime	string	Last time a user connected to this Dev Box, in RFC3339 format.
localAdministrator	LocalAdminStatus	Indicates whether the owner of the Dev Box is a local administrator.
location	string	Azure region where this Dev Box is located. This will be the same region as the Virtual Network it is attached to.
name	string	Display name for the Dev Box.
osType	OsType	The operating system type of this Dev Box.
poolName	string	The name of the Dev Box pool this machine belongs to.
powerState	PowerState	The current power state of the Dev Box.
projectName	string	Name of the project this Dev Box belongs to.
provisioningState	DevBoxProvisioningState	The current provisioning state of the Dev Box.
storageProfile	StorageProfile	Storage settings for this Dev Box.
uniqueId	string	A unique identifier for the Dev Box. This is a GUID-formatted string (e.g. 00000000-0000-0000-0000-000000000000).
uri	string	The unique URI of the dev box.
user	string	The AAD object id of the user this Dev Box is assigned to.

DevBoxProvisioningState

Enumeration

Indicates the provisioning state of the Dev Box.

Value	Description
Canceled	Dev Box provision was canceled.
Creating	Dev Box is being created.
Deleting	Dev Box is being deleted.
Failed	Dev Box failed to provision.
InGracePeriod	Dev Box is in grace period.
NotProvisioned	Dev Box is not provisioned.
ProvisionedWithWarning	Dev Box was provisioned with warning.
Provisioning	Dev Box is provisioning.
Starting	Dev Box is starting.
Stopping	Dev Box is stopping.
Succeeded	Dev Box was successfully provisioned.
Updating	Dev Box is updating.

HardwareProfile

Object

Hardware specifications for the Dev Box.

Name	Type	Description
memoryGB	integer	The amount of memory available for the Dev Box.
skuName	SkuName	The name of the SKU.
vCPUs	integer	The number of vCPUs available for the Dev Box.

HibernateSupport

Enumeration

Indicates whether hibernate is supported and enabled, disabled, or unsupported by the operating system. Unknown hibernate support is represented as null.

Value	Description
Disabled	Hibernate is not enabled.
Enabled	Hibernate is enabled.
OsUnsupported	Hibernate is not supported by the operating system.

ImageReference

Object

Specifies information about the image used.

Name	Type	Description
name	string	The name of the image used.
operatingSystem	string	The operating system of the image.
osBuildNumber	string	The operating system build number of the image.
publishedDate	string	The datetime that the backing image version was published, in RFC3339 format.
version	string	The version of the image.

LocalAdminStatus

Enumeration

Indicates whether owners of Dev Boxes in a pool are local administrators on the Dev Boxes.

Value	Description
Disabled	Owners of Dev Boxes in the pool are not local administrators on the Dev Boxes.
Enabled	Owners of Dev Boxes in the pool are local administrators on the Dev Boxes.

OsDisk

Object

Settings for the operating system disk.

Name	Type	Description
diskSizeGB	integer	The size of the OS Disk in gigabytes.

OsType

Enumeration

The operating system type.

Value	Description
Windows	The Windows operating system.

PowerState

Enumeration

The power states of a Dev Box.

Value	Description
Deallocated	The Dev Box is deallocated.
Hibernated	The Dev Box is hibernated.
PoweredOff	The Dev Box is powered off.
Running	The Dev Box is running.
Unknown	The Dev Box power state is not known.

SkuName

Enumeration

Indicates the Dev Box compute.

Value	Description
general_a_16c64gb1024ssd_v2	AMD, 16 vCPU, 64 GB RAM, 1024 GB Storage.
general_a_16c64gb2048ssd_v2	AMD, 16 vCPU, 64 GB RAM, 2048 GB Storage.
general_a_16c64gb256ssd_v2	AMD, 16 vCPU, 64 GB RAM, 256 GB Storage.
general_a_16c64gb512ssd_v2	AMD, 16 vCPU, 64 GB RAM, 512 GB Storage.
general_a_32c128gb1024ssd_v2	AMD, 32 vCPU, 128 GB RAM, 1024 GB Storage.
general_a_32c128gb2048ssd_v2	AMD, 32 vCPU, 128 GB RAM, 2048 GB Storage.
general_a_32c128gb512ssd_v2	AMD, 32 vCPU, 128 GB RAM, 512 GB Storage.
general_a_8c32gb1024ssd_v2	AMD, 8 vCPU, 32 GB RAM, 1024 GB Storage.
general_a_8c32gb2048ssd_v2	AMD, 8 vCPU, 32 GB RAM, 2048 GB Storage.
general_a_8c32gb256ssd_v2	AMD, 8 vCPU, 32 GB RAM, 256 GB Storage.
general_a_8c32gb512ssd_v2	AMD, 8 vCPU, 32 GB RAM, 512 GB Storage.
general_i_16c64gb1024ssd_v2	Intel, 16 vCPU, 64 GB RAM, 1024 GB Storage.
general_i_16c64gb2048ssd_v2	Intel, 16 vCPU, 64 GB RAM, 2048 GB Storage.
general_i_16c64gb256ssd_v2	Intel, 16 vCPU, 64 GB RAM, 256 GB Storage.
general_i_16c64gb512ssd_v2	Intel, 16 vCPU, 64 GB RAM, 512 GB Storage.
general_i_32c128gb1024ssd_v2	Intel, 32 vCPU, 128 GB RAM, 1024 GB Storage.
general_i_32c128gb2048ssd_v2	Intel, 32 vCPU, 128 GB RAM, 2048 GB Storage.
general_i_32c128gb512ssd_v2	Intel, 32 vCPU, 128 GB RAM, 512 GB Storage.
general_i_8c32gb1024ssd_v2	Intel, 8 vCPU, 32 GB RAM, 1024 GB Storage.
general_i_8c32gb2048ssd_v2	Intel, 8 vCPU, 32 GB RAM, 2048 GB Storage.
general_i_8c32gb256ssd_v2	Intel, 8 vCPU, 32 GB RAM, 256 GB Storage.
general_i_8c32gb512ssd_v2	Intel, 8 vCPU, 32 GB RAM, 512 GB Storage.

StorageProfile

Object

Storage settings for the Dev Box's disks.

Name	Type	Description
osDisk	OsDisk	Settings for the operating system disk.

Share via

Dev Boxes - Create Dev Box

URI Parameters

Request Body

Responses

Security

OAuth2Auth

Scopes

Examples

Creates or replaces a Dev Box.

Sample request

Sample response

Definitions

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

DevBox

DevBoxProvisioningState

HardwareProfile

HibernateSupport

ImageReference

LocalAdminStatus

OsDisk

OsType

PowerState

SkuName

StorageProfile

Additional resources