Share via


Dev Boxes - Create Dev Box

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

minLength: 3
maxLength: 63
pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$

The name of a Dev Box.

endpoint
path True

string (uri)

The DevCenter-specific URI to operate on.

projectName
path True

string

minLength: 3
maxLength: 63
pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$

The DevCenter Project upon which to execute operations.

userId
path True

string

minLength: 2
maxLength: 36
pattern: ^[a-zA-Z0-9]{8}-([a-zA-Z0-9]{4}-){3}[a-zA-Z0-9]{12}$|^me$

The AAD object id of the user. If value is 'me', the identity is taken from the authentication context.

api-version
query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Required Type Description
poolName True

string

minLength: 3
maxLength: 63
pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$

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

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

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

{
  "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"
  }
}
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/azure/Guidelines.md#handling-errors.

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

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

A response containing error details.

Name Type Description
error

Azure.Core.Foundations.Error

The error object.

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/azure/Guidelines.md#handling-errors.

Name Type Description
code

string

One of a server-defined set of error codes.

innererror

Azure.Core.Foundations.InnerError

Inner error.

DevBox

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 (date-time)

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 (date-time)

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

minLength: 3
maxLength: 63
pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$

Display name for the Dev Box.

osType

OsType

The operating system type of this Dev Box.

poolName

string

minLength: 3
maxLength: 63
pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$

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 (uuid)

A unique identifier for the Dev Box. This is a GUID-formatted string (e.g. 00000000-0000-0000-0000-000000000000).

uri

string (uri)

The unique URI of the dev box.

user

string (uuid)

The AAD object id of the user this Dev Box is assigned to.

DevBoxProvisioningState

Indicates the provisioning state of the Dev Box.

Value Description
Succeeded

Dev Box was successfully provisioned.

Failed

Dev Box failed to provision.

Canceled

Dev Box provision was canceled.

Creating

Dev Box is being created.

Deleting

Dev Box is being deleted.

Updating

Dev Box is updating.

Starting

Dev Box is starting.

Stopping

Dev Box is stopping.

Provisioning

Dev Box is provisioning.

ProvisionedWithWarning

Dev Box was provisioned with warning.

InGracePeriod

Dev Box is in grace period.

NotProvisioned

Dev Box is not provisioned.

HardwareProfile

Hardware specifications for the Dev Box.

Name Type Description
memoryGB

integer (int32)

The amount of memory available for the Dev Box.

skuName

SkuName

The name of the SKU.

vCPUs

integer (int32)

The number of vCPUs available 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.

Value Description
Enabled

Hibernate is enabled.

Disabled

Hibernate is not enabled.

OsUnsupported

Hibernate is not supported by the operating system.

ImageReference

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 (date-time)

The datetime that the backing image version was published, in RFC3339 format.

version

string

The version of the image.

LocalAdminStatus

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

Value Description
Enabled

Owners of Dev Boxes in the pool are local administrators on the Dev Boxes.

Disabled

Owners of Dev Boxes in the pool are not local administrators on the Dev Boxes.

OsDisk

Settings for the operating system disk.

Name Type Description
diskSizeGB

integer (int32)

The size of the OS Disk in gigabytes.

OsType

The operating system type.

Value Description
Windows

The Windows operating system.

PowerState

The power states of a Dev Box.

Value Description
Unknown

The Dev Box power state is not known.

Running

The Dev Box is running.

Deallocated

The Dev Box is deallocated.

PoweredOff

The Dev Box is powered off.

Hibernated

The Dev Box is hibernated.

SkuName

Indicates the Dev Box compute.

Value Description
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.

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_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_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_32c128gb512ssd_v2

Intel, 32 vCPU, 128 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_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_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_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_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_32c128gb512ssd_v2

AMD, 32 vCPU, 128 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.

StorageProfile

Storage settings for the Dev Box's disks.

Name Type Description
osDisk

OsDisk

Settings for the operating system disk.