API Endpoint Reference (v3)

v3 (current)v2.0 (legacy)

You are viewing the v3 endpoint reference. v3 is the recommended API for all new integrations.

Switch to the v2.0 endpoint reference for the legacy flat-structure API.

This page lists all user-facing endpoints of the vHaaS REST API v3.

Base URL: https://vhaas.vector.cloud/api/v3

All endpoints require authentication via Authorization: Bearer <JWT> or private-token: <Access Token>, unless stated otherwise. Endpoints marked Admin require the organization_admin or instance_admin role.

Organization scope

Most v3 endpoints are scoped to an organization: /api/v3/organizations/{organization_id}/.... Replace {organization_id} with the UUID of your organization. Use GET /api/v3/self or GET /api/v3/organizations to look up your organization ID.

User & Profile

`GET /api/v3/self`

Returns the profile of the authenticated user, including organization memberships, group memberships, and owned assemblies.

Response fields: user_id, email, display_name, organizations[], groups[]

`GET /api/v3/self/organizations`

Lists all organizations the authenticated user is a member of.

Query param	Type	Description
`search`	string	Filter by organization name.
`page`	integer	Page number (default: 1).
`size`	integer	Items per page (default: 50).

`GET /api/v3/users/{user_id}`

Returns public profile information for a specific user.

`GET /api/v3/users/{user_id}/settings`

Returns the settings for a specific user (own profile only).

`PATCH /api/v3/users/{user_id}/settings`

Updates settings for the authenticated user.

Personal Access Tokens

Tokens scoped to a user for use in scripts and CI pipelines.

Method	Path	Description
`GET`	`/api/v3/users/{user_id}/personal-tokens`	List all personal tokens.
`POST`	`/api/v3/users/{user_id}/personal-tokens`	Create a personal token.
`GET`	`/api/v3/users/{user_id}/personal-tokens/{token_id}`	Get a single token.
`PATCH`	`/api/v3/users/{user_id}/personal-tokens/{token_id}`	Revoke a token.
`DELETE`	`/api/v3/users/{user_id}/personal-tokens/{token_id}`	Delete a token.

Create token request body:

{
  "name": "my-ci-token",
  "expiry_date": "2027-01-01T00:00:00Z"
}

Managing Access Tokens

Organizations

Method	Path	Description	Auth
`GET`	`/api/v3/organizations`	List organizations visible to the authenticated user.	Required
`GET`	`/api/v3/organizations/{organization_id}`	Get a single organization.	Required
`POST`	`/api/v3/organizations`	Create an organization.	Admin
`PATCH`	`/api/v3/organizations/{organization_id}`	Rename an organization.	Admin
`DELETE`	`/api/v3/organizations/{organization_id}`	Delete an organization.	Admin

Query params for GET /organizations:

Param	Type	Description
`search`	string	Filter by name.
`page` / `size`	integer	Pagination.

Organization Users

Manage which users belong to an organization and what roles they hold.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/users`	List users in the organization.	Required
`POST`	`/api/v3/organizations/{org_id}/users`	Add a user to the organization.	Admin
`GET`	`/api/v3/organizations/{org_id}/users/{user_id}`	Get a user's role, groups, and assemblies within the org.	Required
`PATCH`	`/api/v3/organizations/{org_id}/users/{user_id}`	Update a user's role in the organization.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/users/{user_id}`	Remove a user from the organization.	Admin
`GET`	`/api/v3/organizations/{org_id}/users/{user_id}/groups`	List groups the user belongs to in this org.	Required
`PUT`	`/api/v3/organizations/{org_id}/users/{user_id}/favorite-assemblies/{assembly_ref}`	Add an assembly to a user's favorites.	Required
`DELETE`	`/api/v3/organizations/{org_id}/users/{user_id}/favorite-assemblies/{assembly_ref}`	Remove an assembly from a user's favorites.	Required

Query params for GET /users:

Param	Type	Description
`search`	string	Filter by name or email.
`is_technical`	boolean	Filter to technical users (service accounts) only.
`exclude_group_id`	UUID	Exclude users already in a specific group.
`page` / `size`	integer	Pagination.

Groups

Groups organize users and determine which assemblies they can access.

Group Management

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/groups`	List all groups in the organization.	Required
`POST`	`/api/v3/organizations/{org_id}/groups`	Create a group.	Admin
`GET`	`/api/v3/organizations/{org_id}/groups/{group_id}`	Get a single group.	Required
`PATCH`	`/api/v3/organizations/{org_id}/groups/{group_id}`	Rename a group.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/groups/{group_id}`	Delete a group.	Admin

Group Users

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/groups/{group_id}/users`	List users in the group.	Required
`POST`	`/api/v3/organizations/{org_id}/groups/{group_id}/users`	Add a user to the group.	Admin
`PATCH`	`/api/v3/organizations/{org_id}/groups/{group_id}/users/{user_id}`	Update a user's role in the group.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/groups/{group_id}/users/{user_id}`	Remove a user from the group.	Admin

Group Assemblies

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/groups/{group_id}/assemblies`	List assemblies assigned to the group.	Required
`POST`	`/api/v3/organizations/{org_id}/groups/{group_id}/assemblies`	Assign an assembly to the group.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/groups/{group_id}/assemblies/{assembly_ref}`	Remove an assembly from the group.	Admin

Group Service Tokens

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/groups/{group_id}/service-tokens`	List service tokens for the group.	Group Admin
`POST`	`/api/v3/organizations/{org_id}/groups/{group_id}/service-tokens`	Create a group service token.	Group Admin
`GET`	`/api/v3/organizations/{org_id}/groups/{group_id}/service-tokens/{token_id}`	Get a service token.	Group Admin
`DELETE`	`/api/v3/organizations/{org_id}/groups/{group_id}/service-tokens/{token_id}`	Delete a service token.	Group Admin

Assemblies

An Assembly is a logical grouping of physical hardware (ECUs, interfaces, power supplies) available for remote access.

Assembly Collection

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/assemblies`	List assemblies visible to the user.	Required
`GET`	`/api/v3/organizations/{org_id}/assemblies/enriched`	List assemblies with full VM, group, and status details.	Required
`POST`	`/api/v3/organizations/{org_id}/assemblies`	Create an assembly.	Admin

Query params for GET /assemblies:

Param	Type	Description
`search`	string	Filter by name or reference.
`cluster_ref`	string	Filter by cluster.
`favorite`	boolean	Show only favorite assemblies.
`page` / `size`	integer	Pagination.

Additional query params for /assemblies/enriched:

Param	Type	Description
`status_type[]`	string	Filter by board status.
`group[]`	string	Filter by group ID.
`vm_hostname[]`	string	Filter by VM hostname.
`supplier[]` / `family[]` / `variant[]`	string	Filter by hardware catalog attributes.
`user_name`	string	Filter by current session owner.

Assembly Detail

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/assemblies/{assembly_ref}`	Get a single assembly.	Required
`PATCH`	`/api/v3/organizations/{org_id}/assemblies/{assembly_ref}`	Update assembly metadata.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/assemblies/{assembly_ref}`	Delete an assembly.	Admin

Device Sequences

Ordered lists of switching steps saved on an assembly. All paths below are relative to /api/v3/organizations/{org_id}/assemblies/{assembly_ref}.

Method	Path	Description	Auth
`GET`	`…/device-sequences`	List the device sequences of an assembly.	Required
`POST`	`…/device-sequences`	Create a device sequence.	Required
`GET`	`…/device-sequences/{sequence_id}`	Get a device sequence.	Required
`PATCH`	`…/device-sequences/{sequence_id}`	Update a device sequence.	Required
`DELETE`	`…/device-sequences/{sequence_id}`	Delete a device sequence.	Required
`POST`	`…/device-sequences/{sequence_id}/run`	Execute a device sequence.	Required
`GET`	`…/device-sequences/{sequence_id}/run`	List the latest runs of a sequence.	Required
`GET`	`…/device-sequences/{sequence_id}/run/{run_id}`	Get the status of a specific run.	Required
`PATCH`	`…/device-sequences/{sequence_id}/run/{run_id}`	Update the run status, e.g. to cancel a running sequence.	Required

A run is executed asynchronously: POST …/run returns immediately and the run reports its progress through its own status. Runs of the same assembly's virtual machine are serialized.

Manage Device Sequences

Sessions & Bookings

A session (booking) grants exclusive access to an assembly for a defined time window.

Assembly Sessions

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/assembly-sessions`	List sessions.	Required
`POST`	`/api/v3/organizations/{org_id}/assembly-sessions`	Create (book) a session.	Required
`GET`	`/api/v3/organizations/{org_id}/assembly-sessions/{session_id}`	Get session status and details.	Required
`PATCH`	`/api/v3/organizations/{org_id}/assembly-sessions/{session_id}`	Update session (e.g. extend end time).	Required
`DELETE`	`/api/v3/organizations/{org_id}/assembly-sessions/{session_id}`	Release a session immediately.	Required
`GET`	`/api/v3/organizations/{org_id}/assembly-sessions/{session_id}/session-tasks`	Get tasks associated with a session.	Required

Query params for GET /assembly-sessions:

Param	Type	Description
`assembly_ref`	string	Filter by assembly reference.
`start_time`	datetime	Filter sessions starting after this timestamp.
`end_time`	datetime	Filter sessions ending before this timestamp.
`page` / `size`	integer	Pagination.

Create session request body:

{
  "assembly_ref": "ASSEMBLY-101",
  "start_time": "2026-07-01T08:00:00Z",
  "end_time": "2026-07-01T17:00:00Z"
}

Session Contexts

A session context is the active environment established when a booked session starts (credentials, connection parameters).

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/assembly-session-contexts`	List session contexts.	Required
`POST`	`/api/v3/organizations/{org_id}/assembly-session-contexts`	Create a session context.	Required
`GET`	`/api/v3/organizations/{org_id}/assembly-session-contexts/{context_id}`	Get a session context.	Required
`DELETE`	`/api/v3/organizations/{org_id}/assembly-session-contexts/{context_id}`	Delete a session context.	Required

Session Transfers

Transfer ownership of an active session to another user.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/assembly-session-transfers`	List transfer requests.	Required
`POST`	`/api/v3/organizations/{org_id}/assembly-session-transfers`	Request a session transfer.	Required
`PATCH`	`/api/v3/organizations/{org_id}/assembly-session-transfers/{transfer_id}`	Approve or reject a transfer request.	Required

Create transfer request body:

{
  "assembly_ref": "ASSEMBLY-101",
  "new_user_id": "user-uuid",
  "force": false
}

Approve / reject body:

{
  "response": "approve"
}

Jobs

Jobs represent scheduled or running automation tasks on an assembly.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/jobs`	List jobs.	Required
`POST`	`/api/v3/organizations/{org_id}/jobs`	Create a job.	Required
`GET`	`/api/v3/organizations/{org_id}/jobs/{job_id}`	Get a single job.	Required
`DELETE`	`/api/v3/organizations/{org_id}/jobs/{job_id}`	Cancel / delete a job.	Required

Query params for GET /jobs:

Param	Type	Description
`job_ids[]`	UUID	Filter by specific job IDs.
`user_ids[]`	string	Filter by user.
`status`	string	Filter by status (e.g. `running`, `completed`, `failed`).
`page` / `size`	integer	Pagination.

Virtual Machines

Virtual Machines (VMs) provide the remote development environment paired with an assembly.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/virtual-machines`	List VMs.	Required
`POST`	`/api/v3/organizations/{org_id}/virtual-machines`	Create a VM.	Admin
`GET`	`/api/v3/organizations/{org_id}/virtual-machines/{vm_id}`	Get a single VM.	Required
`PATCH`	`/api/v3/organizations/{org_id}/virtual-machines/{vm_id}`	Update VM properties.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/virtual-machines/{vm_id}`	Delete a VM.	Admin
`GET`	`/api/v3/organizations/{org_id}/virtual-machines/{vm_id}/credentials`	Get VM credentials.	Admin
`POST`	`/api/v3/organizations/{org_id}/virtual-machines/{vm_id}/credentials`	Set VM credentials.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/virtual-machines/{vm_id}/credentials`	Delete VM credentials.	Admin

Query params for GET /virtual-machines:

Param	Type	Description
`assigned`	boolean	`true` = only VMs assigned to an assembly, `false` = unassigned only.
`cluster_ref`	string	Filter by cluster.
`assembly_refs[]`	string	Filter by specific assembly references.
`search`	string	Filter by hostname.
`page` / `size`	integer	Pagination.

Clusters

Clusters group the physical infrastructure (NUCs, network segments) that host assemblies.

Cluster Management

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/clusters`	List clusters.	Required
`POST`	`/api/v3/organizations/{org_id}/clusters`	Create a cluster.	Admin
`GET`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}`	Get a single cluster.	Required
`PATCH`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}`	Update cluster metadata.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}`	Delete a cluster.	Admin

Cluster Partitions

Partitions segment a cluster into isolated network zones.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/clusters/cluster-partitions`	List all partitions across the org.	Required
`GET`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-partitions`	List partitions for a cluster.	Required
`POST`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-partitions`	Create a partition.	Admin
`PATCH`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-partitions/{partition_id}`	Update a partition.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-partitions/{partition_id}`	Delete a partition.	Admin

Cluster IPs & Sensors

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips`	List cluster IP entries.	Required
`POST`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips`	Add a cluster IP.	Admin
`GET`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips/{ip_id}`	Get a cluster IP.	Required
`PATCH`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips/{ip_id}`	Update a cluster IP.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips/{ip_id}`	Delete a cluster IP.	Admin
`GET`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips/{ip_id}/sensor-configs`	List sensor configurations for an IP.	Required
`GET`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips/{ip_id}/sensor-configs/{sensor_number}`	Get a specific sensor config.	Required
`PATCH`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/cluster-ips/{ip_id}/sensor-configs/{sensor_number}`	Update a sensor config.	Admin

Cluster Assemblies

Method	Path	Description	Auth
`POST`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/assemblies`	Assign an assembly to a cluster.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/clusters/{cluster_ref}/assemblies/{assembly_ref}`	Remove an assembly from a cluster.	Admin

Hardware Catalog

The hardware catalog defines the device types (suppliers, families, versions) that can be used in assembly profiles.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/hardware/device-suppliers`	List device suppliers.	Required
`GET`	`/api/v3/organizations/{org_id}/hardware/device-suppliers/{supplier_id}`	Get a supplier.	Required
`GET`	`/api/v3/organizations/{org_id}/hardware/device-suppliers/{supplier_id}/families`	List device families for a supplier.	Required
`GET`	`/api/v3/organizations/{org_id}/hardware/device-suppliers/{supplier_id}/families/{family_id}`	Get a device family.	Required
`GET`	`/api/v3/organizations/{org_id}/hardware/device-suppliers/{supplier_id}/families/{family_id}/versions`	List device versions for a family.	Required

Metrics & Monitoring

Query time-series metrics for assemblies, virtual machines, and clusters.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/metrics/assembly-panels`	Get assembly metrics (CPU, memory, network, disk, embedded hardware).	Required
`GET`	`/api/v3/organizations/{org_id}/metrics/virtual-machine-panels`	Get VM metrics.	Required
`GET`	`/api/v3/organizations/{org_id}/metrics/cluster-panels`	Get cluster metrics.	Required

Query params (all metrics endpoints):

Param	Type	Description
`assembly_ref` / `virtual_machine_id` / `cluster_ref`	string	ID of the resource to query.
`query_key`	string	Metric panel identifier (e.g. `cpu_load`, `memory`, `network`).
`start`	datetime	Start of the time range.
`end`	datetime	End of the time range.
`step`	string	Resolution step (e.g. `1m`, `5m`, `1h`).

Announcement Banners

System-wide or assembly-scoped notification messages shown in the Web UI.

Announcement Banners (global per org)

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/announcement-banners`	List announcement banners.	Required
`POST`	`/api/v3/organizations/{org_id}/announcement-banners`	Create an announcement banner.	Admin
`PATCH`	`/api/v3/organizations/{org_id}/announcement-banners/{banner_id}`	Update a banner.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/announcement-banners/{banner_id}`	Delete a banner.	Admin

Assembly Banners (scoped to specific assemblies)

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/banners`	List assembly-scoped banners.	Required
`POST`	`/api/v3/organizations/{org_id}/banners`	Create an assembly banner.	Admin
`PATCH`	`/api/v3/organizations/{org_id}/banners/{banner_id}`	Update a banner.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/banners/{banner_id}`	Delete a banner.	Admin

Organization Service Tokens

Long-lived tokens scoped to an organization, used for CI runners and automation pipelines.

Method	Path	Description	Auth
`GET`	`/api/v3/organizations/{org_id}/service-tokens`	List organization service tokens.	Admin
`POST`	`/api/v3/organizations/{org_id}/service-tokens`	Create an organization service token.	Admin
`GET`	`/api/v3/organizations/{org_id}/service-tokens/{token_id}`	Get a service token.	Admin
`PATCH`	`/api/v3/organizations/{org_id}/service-tokens/{token_id}`	Revoke a service token.	Admin
`DELETE`	`/api/v3/organizations/{org_id}/service-tokens/{token_id}`	Delete a service token.	Admin

Health & System

Method	Path	Description	Auth
`GET`	`/api/v3/config`	Returns OIDC configuration for the frontend.	None
`GET`	`/livez`	Kubernetes liveness probe.	None
`GET`	`/readyz`	Kubernetes readiness probe (includes database connectivity check).	None