Breadcrumbs

Hydra REST API

Overview

Hydra has a limited set of REST web API calls to manage session hosts, scripts, and images.

To enable this feature, create a new secret in the Key Vault deployed with Hydra (you have to give yourself access to the secrets of the Key Vault first).

Name

Secret value

Hydra-RESTAccess

A complex (URL encoded) self-defined secret with at least 32 characters. Make this complex to secure access.

If the secret doesn’t exist, is empty, or has fewer than 32 characters, Hydra will not accept REST calls.

After creating or changing the secret, a restart of Hydra (the app service) is necessary. Do this only if no imaging or deployment is currently running. You can restart Hydra by:

  1. Clicking on the Avatar menu (upper-right corner).

  2. Selecting Restart Engine.

Authorization

Hydra REST API uses the Authorization header for authentication.

Header

Value

Authorization

"SharedKey "

Available Endpoints

Create a new host

Endpoint

Request body

Response

POST /rest/hostpools/<HostPool-Guid>/addhostspartial

Can contain:

  • VmSize: String; e.g., Standard_D8as_v5

  • AssigneUser: String; e.g., user@domain.com (only for personal pools)

  • DiskSizeInGb: Number; Size of the OS disk

  • PoolGroup: string; custom, only valid if the host pool Guid is Guid.Empty (must match one of the pools with the deployment tag "AVD.PoolGroup"

  • Other properties are used from the default deployment configuration of the host pool

A GUID to query the state of the task.

Delete a host with VM

Endpoint

Request body

Response

GET /rest/sessionhosts/<SessionHost-Guid>/delete

-

A GUID to query the state of the task.

Change VM size and/or OS-disk size a host with VM

VM will be started and stopped.

Endpoint

Request body

Response

POST /rest/sessionhosts/<SessionHost-Guid>/resize

Can contain (one or both settings):

  • VmSize: String; e.g. Standard_D8as_v5

  • DiskSizeGb: Int; Size of the OS-Disk in GByte (increase only; the VM is also started to expand the partition)

A GUID to query the state of the task.

Get assigned session hosts for a user

Endpoint

Request body

Response

GET /rest/hostpools/<HostPool-Guid/users/<UPN>/sessionhosts

-

A list of session hosts where the user is assigned. If HostPool-Guid is a GUID. Empty, all assigned hosts in all pools are returned.

Get available scripts for a user

Endpoint

Request body

Response

GET /rest/scripts

-

A list of scripts.

Get available script collections

Endpoint

Request body

Response

GET /rest/scriptcollections

-

A list of script collections.

Run a script or script collection on a host

Endpoint

Request body

Response

POST /rest/sessionhosts/<SessionHost-Guid>/scriptorscriptcollection

Should contain the ID of the script or collection as text.

A GUID to query the state of the task.

Get the list of imaging definitions

Endpoint

Request body

Response

GET /rest/azure/imagingDefinitions

-

A list of ImagingDefinition.

Save and run a imaging definition

Endpoint

Request body

Response

POST /rest/scenes/<SceneId>/StartStoredImageDefinition

<ImagingDefinition>

A GUID to query the state of the task.

Get the state of tasks

Endpoint

Request body

Response

GET /rest/actions/<task-guid>

-

  • 200: Done successfully

  • 404: Not found

  • 202: Still running

  • 409: Failed

Optional filtering

HTTP-Get commands to query VMs by user or to delete a host can have an additional filter in the header:

Filter

Value

Description

"LimitToSubscriptions"

"49f90bf9-ddf8-48b2-bf90-629f3dbef550,f7f733a1-92f8-4ff4-8e49-6ecd7c3533f3"

Filters by subscriptions of the VMs/hosts.

"LimitToPoolGroups"

"engineering,sales"

Filters by pool groups.

"LimitToPoolType"

"personal"

Filters by host pool type: personal or pooled.