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.

Note: 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

Note: 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.