veHaaS API

All features available on the veHaaS website are also accessible through the REST API.

Authentication

Every request must include one of the following HTTP headers:

Header	Value	When to use
`Authorization`	`Bearer <JWT Token>`	Used automatically by the Web UI with a token issued by the Azure Identity Provider.
`private-token`	`<Access Token>`	Use this in scripts, CI pipelines, and the CLI. Accepts personal and organizational access tokens.

Access tokens can be created in the veHaaS Web UI at personal, group, or organization scope.

https://vehaas.vi.vector.int/api/v2.0/

The API is fully documented in the live Swagger UI:

Click Authorize at the top of the page and enter your access token to send requests directly from the browser.

An OpenAPI-compliant spec is available at:

https://vehaas.vi.vector.int/api/v2.0/openapi.json

You can use this with the OpenAPI Generator to auto-generate a client in almost any language.

The API is organised into the following resource groups:

Resource group	Description
`access-tokens`	Create and manage personal, group, and organization access tokens.
`assemblies`	List, create, update, and delete Assemblies; manage devices, owners, power states, and connections.
`assembly-group-relationships`	Query which Assemblies belong to which Groups.
`assembly-session-contexts`	Manage the session context established when a booking becomes active (credentials, environment).
`assembly-session-transfers`	Initiate, accept, and reject session transfer requests between users.
`assembly-sessions`	Create (allocate), query, update, and release Assembly sessions.
`banners`	Read and manage system-wide or organization-scoped notification banners.
`clusters`	Manage Clusters and their partitions, IP ranges, and sensor configurations.
`default`	Root endpoint and version information.
`deprecation-info`	Query which API endpoints or features are deprecated and when they will be removed.
`groups`	Create and manage Groups and their memberships.
`health`	Service health check endpoint.
`jobs`	Read and manage internal scheduling jobs (read-only for most users).
`monitoring`	Query Assembly liveness and device monitoring metrics.
`organizations`	Read organization membership and manage organization-level settings.
`users`	Read and update user profiles, settings, variables, and RDP configuration.
`virtual-machines`	Create, update, and delete Virtual Machines; manage VM credentials.

The most commonly used endpoints for day-to-day automation and CI integration:

Method	Path	Description
`GET`	`/api/v2.0/assemblies`	List all Assemblies visible to you, with optional filtering.
`GET`	`/api/v2.0/assemblies/{assembly_ref}`	Get a single Assembly by reference (e.g. `ASSEMBLY-101`).
`POST`	`/api/v2.0/assembly-sessions`	Create (allocate) an Assembly session.
`GET`	`/api/v2.0/assembly-sessions/{session_id}`	Get the status and details of an active session.
`PATCH`	`/api/v2.0/assembly-sessions/{session_id}`	Update a session (e.g. extend end time).
`DELETE`	`/api/v2.0/assembly-sessions/{session_id}`	Release a session immediately.
`GET`	`/api/v2.0/users/self`	Get the profile of the currently authenticated user.
`GET`	`/api/v2.0/virtual-machines`	List Virtual Machines accessible to you.

Using the CLI instead

For most of these operations there is a dedicated CLI command. See the Command Line Tool reference for details.

List endpoints support pagination via two query parameters:

Parameter	Type	Default	Description
`skip`	integer	`0`	Number of entries to skip (offset).
`limit`	integer	`100`	Maximum number of entries to return. Maximum allowed value: `1 000 000`.

Example:

GET /api/v2.0/assemblies?skip=0&limit=50

All error responses use a consistent JSON shape:

{
  "detail": "A human-readable description of what went wrong."
}

Common HTTP status codes:

Code	Meaning
`400`	Bad request — the request body or parameters are malformed.
`401`	Unauthorized — no valid authentication token was provided.
`403`	Forbidden — the token is valid but does not have permission for this resource.
`404`	Not found — the requested resource does not exist.
`409`	Conflict — the request conflicts with the current state (e.g. Assembly already allocated).
`422`	Validation error — the request was structurally valid but failed field-level validation.
`500`	Internal server error — contact Support if this persists.

The veHaaS CLI (pes-vehaas Python package) wraps the full API and is the recommended way to interact with veHaaS from scripts and pipelines.

Download the OpenAPI spec and use the OpenAPI Generator to generate a typed client in any supported language:

openapi-generator generate \
  -i https://vehaas.vi.vector.int/api/v2.0/openapi.json \
  -g python \
  -o ./vehaas-client