Velocity API specification v 1.0

This is the 1.0 version of the Velocity API specification.

The Velocity API uses JSON as its language.

Hierarchy

Velocity manages virtual machines and resources seperately.

For resources, velocity uses so-called "pools" and virtual machines are managed in "catalogs".

The API is divided into several namespaces:

  • /u: User and group management
  • /m: Pool and media management
  • /v: Virtual machine management

Authentication

Velocity handles authentication using the Bearer authentication method with the token being aliased as the Authkey.

Refer to the Vapor manual for more information.

Errors

If the API enconters some kind of error, it will respond with a http-response code in a non-200 range and an error as follows:

{
  "code": "<Error code>",
  "message": "<Some error message (optional)>"
}

Some additional fields may be added to the error response depending on calls but this layout is guaranteed.

For an exhaustive list of available error codes, refer to the ERRORS article.

Some http-response codes are fixed:

  • 400 - Bad Request: The request is missing fields

  • 401 - Unauthorized: The request is missing the authkey for privileged actions

  • 500 - Internal Server Error: The server encountered an error while processing the request

Entity hierarchy

Velocity's main work horse are groups. Each Virtual machine is owned by a group, wich is owned by another parent group. All the way up to the root group (0).

Each user can be assigned to a group with permissions. These permissions for groups persist for all subgroups. This allows a user that has a permission in a parent group to use it in subgroups. This allows for building a structured and manageable entity and user tree.

For permissions, read the PERMISSIONS article.

classDiagram
    Group <|-- Group: Subgroup
    Pool <|-- Pool: Subpool
    Group <|-- User: Has permissions on
    Group --|> Pool: Has permissions on
    Pool <|-- Media: Is part of
    Group: gid
    Group: name

    User: uid
    User: name
    User: password

    Pool: pid
    Pool: name
    Pool: quota_mib

    Media: mid
    Media: name
    Media: size_mib

Errors

This is an exhaustive list of error codes that can be returned by the Velocity API.

Codes:

The error codes do have some structure:

The last 2 digits indicate the error:

  • 0x Indicates a permission error

  • 1x Indicates that something hasn't been found

  • 2x Indicates conflicts and not allowable actions

The next digit indicates the method:

  • 0: other codes

  • 1: POST

  • 2: PUT

  • 3: DELETE

  • 4: PATCH

And the others are reserved for the rest (contexts, endpoints, routes, etc...)

Example:

If a route has the error id 12 and wants to indicate a permission error on the PATCH method, the error code is the following:

1230x

General

  • 100 > 403: An authkey is needed for the request but it has expired or does not exist

/u

/u/auth

POST

  • 1100 > 403: Authentication failed (username or password do not match)

PATCH

  • 1400 > 403: The old authkey hasn't been found

  • 1401 > 403: The old authkey has expired

/u/user

POST

  • 2100 > 403: Permission velocity.user.view is needed

  • 2110 > 404: User has not been found

PUT

  • 2200 > 403: Permission velocity.user.create is needed

  • 2220 > 409: A user with the same name exists

DELETE

  • 2300 > 403: Permission velocity.user.remove is needed

  • 2310> 404: User has not been found

/u/user/list

POST

  • 3100 > 403: Permission velocity.user.list is needed

/u/user/permission

PUT

  • 4200 > 403: Permission velocity.user.assign is needed

  • 4210 > 404: User has not been found

  • 4211 > 404: Group has not been found

  • 4212 > 404: Permission has not been found

  • 4220 > 403: Assigned permission is too high

DELETE

  • 4300 > 403: Permission velocity.user.revoke is needed

  • 4310 > 404: User has not been found

  • 4311 > 404: Group has not been found

  • 4312 > 404: Permission has not been found

/u/group

POST

  • 5100 > 403: Permission velocity.group.view is needed

  • 5110 > 404: roup has not been found

PUT

  • 5200 > 403: Permission velocity.group.create is needed

  • 5210 > 404: Parent group has not been found

  • 5220 > 409: A group with the same name exists within the parent group

DELETE

  • 5300 > 403: Permission velocity.group.remove is needed

  • 5310 > 404: Group has not been found

/m/pool/assign

PUT

  • 6200 > 403: Permission velocity.pool.assign is needed

  • 6210 > 404: Group has not been found

  • 6211 > 404: Mediapool has not been found

DELETE

  • 6300 > 403: Permission velocity.pool.revoke is needed

  • 6310 > 404: Group has not been found

  • 6311 > 404: Mediapool has not been found

/m/pool/list

POST

  • 7100 > 403: Permission velocity.pool.list is needed

  • 7110 > 404: Group has not been found

/m/media/create

PUT

  • 8200 > 403: Permission velocity.media.create is needed

  • 8201 > 403: Group does not have the manage permission on the media pool

  • 8210 > 404: Group has not been found

  • 8211 > 404: Mediapool has not been found

  • 8220 > 409: The filename is a duplicate

  • 8221 > 406: Some quota has been surpassed

/m/media/upload

PUT

  • 9200 > 403: Permission velocity.media.create is needed

  • 9201 > 403: Group does not have the manage permission on the media pool

  • 9210 > 400: The Content-Length header field is missing

  • 9211 > 400: The x-velocity-authkey header field is missing

  • 9212 > 400: The x-velocity-mpid header field is missing

  • 9213 > 400: The x-velocity-gid header field is missing

  • 9214 > 400: The x-velocity-name header field is missing

  • 9215 > 400: The x-velocity-type header field is missing

  • 9216 > 400: The x-velocity-readonly header field is missing

  • 9217 > 404: Group has not been found

  • 9218 > 404: Mediapool has not been found

  • 9220 > 409: The filename is a duplicate

  • 9221 > 406: Some quota has been surpassed

  • 9222 > 413: More bytes than specified in Content-Length have been submitted

/m/media/list

POST

  • 10100 > 403: Permission velocity.media.list is needed

  • 10110 > 404: Group has not been found

/v/nic/list

POST

  • 11100 > 403: Permission velocity.nic.list is needed

/v/vm/efi

PUT

  • 12200 > 403: Permission velocity.vm.create is needed
  • 12210 > 404: Group has not been found
  • 12211 > 404: Media has not been found
  • 12212 > 404: Media-owning group has not been found
  • 12213 > 404: Media-hosting mediapool has not been found
  • 12214 > 404: Host NIC has not been found
  • 12220 > 403: CPU quota surpassed
  • 12221 > 403: Memory quota surpassed
  • 12222 > 403: Media quota surpassed
  • 12223 > 403: VM name is a duplicate
  • 12224 > 403: Display name is a duplicate
  • 12225 > 403: Invalid disk mode
  • 12226 > 403: Invalid NIC type
  • 12227 > 403: BRIDGE NIC needs a host NIC

Permissions

This is an extensive list that lists every permission that is available in the Velocity system.

velocity

The namespace for all velocity permissions

user (velocity.user)

User management

create (velocity.user.create)

Create new users.

Note

Do keep in mind that this permission allows a user to create new users for the system and thus consume unique usernames!

remove (velocity.user.remove)

Remove users that are in the group from the system.

Note

This destroys users at the system level, if a user should only be able to revoke a user from a group, it should have the revoke permission

assign (velocity.user.assign)

Assign new users to the group

revoke (velocity.user.revoke)

Remove users from the group

view (velocity.user.view)

Get user information about other users

list (velocity.user.list)

List all users of the velocity instance

group (velocity.group)

Group management

create (velocity.group.create)

Create a new subgroup to the group

remove (velocity.group.remove)

Remove a subgroup

view (velocity.group.view)

Retrieve information about the group and all of its members an permissions

pool (velocity.pool)

Pool permissions

list (velocity.pool.list)

List pools available to a group

assign (velocity.pool.assign)

Assign a group to a pool

revoke (velocity.pool.revoke)

Revoke a group's permissions from a mediapool

media (velocity.media)

Media permissions

list (velocity.media.list)

List media in a group

create (velocity.media.create)

Create media in a group

remove (velocity.media.remove)

Remove media from a group (delete it)

vm (velocity.vm)

create (velocity.vm.create)

Create a new virtual machine in the group

remove (velocity.vm.remove)

Remove a virtual machine from the group

alter (velocity.vm.alter)

Alter a virtual machine parameters (CPU, RAM...)

view (velocity.vm.view)

View statistics for a virtual machine

interact (velocity.vm.interact)

Interact with a virtual machine (RFB, Serial...)

state (velocity.vm.state)

Alter the virtual machine state (start, stop, pause...)

nic (velocity.nic)

list (velocity.nic.list)

List available host NICs

User and group management: /u

Velocity's concept of users and groups is similar to that of Unix. Permissions, vm and data pools are always connected to groups due to them being able to be shared across users with a fair amount of granularity.

There is one special group GID set to 0. This is the supergroup that has full access to everything. All other groups descend from that group and get delegated. This group's parent gid is set to 0, creating a recursion to signal the root group.

User

Each user is identified by its unique UID, its username and password.

Group

Each group has a parent group and can inherit some of the parent group's quotas, but never surpass them.

Permission

A user can be assigned to a group with permissions. These permissions will be inherited to subgroups: When a user has a permission on a group, it also applies to all of its subgroups.

Available endpoints

Authentication

User management

Permission management

Group management

Authentication

/u/auth - POST

Velocity's authentication model works using so-called 'authkeys'. Every user that is currently authenticated gets such a key that has a certain validity window. Every privileged action that requires authentication requires this authkey to be sent with the request. To obtain such an authkey, a user can issue an authentication to this endpoint.

Request:

{
  "name": "<username>",
  "password": "<password>"
}

The password and username get transmitted in plaintext. It is assumed that the connection to the API uses HTTPS.

Response:

  • 200: Authenticated
{
  "authkey": "<authkey>",
  "expires": "<unix timestamp>"
}
  • 403 - Forbidden: Authentication failed - username or password do not match

Every authkey has an expiration date that is transmitted in the unix timestamp format. The key has to be renewed before this date is passed for the key to stay valid.

/u/auth - DELETE

If a user desires to drop the current authkey immediately, this endpoint can be used for that.

Request:

{
  "authkey": "<authkey>"
}

Response:

  • 200: Authkey dropped

Note

For security reasons, dropping a non-existing authkey does still result in a 200 response code.

/u/auth - PATCH

If an authkey lease is about to expire, this call can be used to create a new authkey using the expiring key.

Note

This will immediately drop the old authkey in favor of the newly generated one

Request:

{
  "authkey": "<authkey>"
}

Response:

  • 200: Authkey refreshed
{
  "authkey": "<new authkey>",
  "expires": "<unix timestamp>"
}
  • 403 - Forbidden: Tried to renew a non-existing / expired authkey

User management

/u/user - POST

Retrieve information about the current user. The request's authkey is used to infer the user, unless the uid field is specified.

Note

To query information about other users, the calling user needs the velocity.user.view permission

Request:

{
  "uid": "<UID (optional)>"
}

Response:

  • 200
{
  "uid": "<UID>",
  "name": "<User name>",
  "memberships": [
    {
      "gid": "<GID>",
      "parent_gid": "<GID>",
      "name": "<Group name>",
      "permissions": [
        {
          "pid": "<PID>",
          "name": "<Permission name>",
          "description": "<Permission description>"
        }
      ]
    }
  ]
}
  • 403 - Forbidden: The calling user lacks permissions to view other user's information
  • 404 - Not Found: The desired uid hasn't been found

/u/user - PUT

Create a new user

Note

Only users that have the velocity.user.create permission

Request:

{
  "name": "<username>",
  "password": "<password>"
}

Response:

  • 200: User created
{
  "uid": "<UID>",
  "name": "<username>"
}

  • 403 - Forbidden: The current user is not allowed to create new users

  • 409 - Conflict: A user with the supplied username does already exist

/u/user - DELETE

Note

Only users that have the velocity.user.remove permission for the user's parent group can remove users

This call removes the user with the supplied UID. This also removes the user's group that is named the same as the user and all of its VMs and images.

Request:

{
  "uid": "<UID>"
}

Response:

  • 200: User removed

  • 403 - Forbidden: The current user is not allowed to remove users

  • 404 - Not Found: No user with the supplied uid has been found

/u/user/list - POST

List all users on this velocity instance

Note

The calling user needs the velocity.user.list permission

Request:

<NO BODY>

Response:

  • 200
{
  "users": [
    {
      "uid": "<UID>",
      "name": "<username>"
    }
  ]
}
  • 403 - Forbidden: The calling user lacks permissions

Permission management

/u/user/permission - PUT

Put new permissions for a user on a specific group

Note

A user cannot assign other users to higher groups than its own. He needs the velocity.user.assign permission for the group to assign to

Note

A user can only forward permissions itself has. If the user tries to give permissions to another user that it doesn't have, this call will fail

Request:

{
  "uid": "<UID>",
  "gid": "<GID>",
  "permission": "<permission identifier>"
}

The permissions array lists the permissions that the user should receive.

Response:

  • 200: Permission added

  • 403 - Forbidden: The user tried to assign to a higher group, higher permissions or does not have the required permissions

  • 404 - Not Found: The uid or gid or permission name has not been found

/u/user/permission - DELETE

Remove user permissions

Note

Only users that have the velocity.user.revoke permission for the target group can do this

Request:

{
  "uid": "<UID>",
  "gid": "<GID>",
  "permission": "<permission>"
}

The permission field is optional. If it is set, this will remove the listed permissions on the target group if available. If this field is omitted, this will remove the user completely, revoking all permissions.

Response:

  • 200: Permission removed

  • 403 - Forbidden: The current user is not allowed to remove from groups (velocity.user.revoke permission) or does not have the removed permission

  • 404 - Not Found: The uid, gid or permission name has not been found

Group management

/u/group - POST

Retrieve information about a group

Note

The calling user needs the velocity.group.view permission on the requested group

Request:

{
  "gid": "<GID>"
}

Response:

  • 200
{
  "gid": "<GID>",
  "parent_gid": "<GID>",
  "name": "<Group name>",
  "memberships": [
    {
      "uid": "<UID>",
      "name": "<User name>",
      "permissions": [
        {
          "pid": "<PID>",
          "name": "<Permission name>",
          "description": "<Permission description>"
        }
      ]
    }
  ]
}

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The gid could not be found

/u/group - PUT

Create a new group. There cannot be duplicate group names in a parent group.

Note

The user needs the velocity.group.create permission on the parent group

Request:

{
  "name": "<groupname>",
  "parent_gid": "<GID>"
}

Response:

  • 200: Group created
{
  "gid": "<GID>",
  "name": "<groupname>",
  "parent_gid": "<GID>"
}

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The parent_gid does not exist

  • 409 - Conflict: A group with the supplied groupname within the parent group does already exist

/u/group - DELETE

Remove a group from a parent group

Note

The user needs the velocity.group.remove permission on the parent group

This call removes all the VMs and images owned by this group.

Request:

{
  "gid": "<GID>"
}

Response:

  • 200: Group removed

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The gid does not exist

/u/group/list - POST

List back all existing groups on this velocity instance

Note

The calling user needs at least one permission on a group for its name (and subgroups) to be displayed.

Do note that groups that are essential to recreating the tree will get listed, too

Request:

<NO BODY>

Response:

  • 200
{
  "groups": [
    {
      "gid": "<GID>",
      "parent_gid": "<GID>",
      "name": "<Group name>",
      "permissions": [
        {
          "pid": "<PID>",
          "name": "<Permission name>",
          "description": "<Permission description>"
        }
      ]
    }
  ]
}

The permissions field does only list direct permissions (not inherited ones)

Media management

A virtual machine needs media to work with. Velocity attaches media to a group and stores it in pools, giving groups read or write access. Pools cannot be created via the API, but are rather defined by the Velocity host configuration.

The pool id (mpid) identifies the pool, but does not hold any reference to where the data is stored. This allows for pools to be moved on the filesystem without loosing references to the files. The Velocity administrator is in charge of tracking the pool ids.

Warning

The administrator is in charge of keeping the mpid stable between restarts and configuration changes, else media references may become invalid

A pool allows groups to access media with two permissions:

  • write: Write to the media (if it is not read-only)

  • manage: Create / remove media from this pool

Every piece of media is identified by its media id (mid) that is a UUID string and its type, which can be anything, but some strings are recommended:

  • ISO: ISO images for bootable read-only media

  • DISK: Disk images to use for virtual machine storage devices

  • IPSW: macOS restore / installer images

Available endpoints

Pool management

Media management

Pool management

/m/pool/assign - PUT

Assign a group to a mediapool with permissions

If the group is already assigned to the pool, this call will update the permissions

Note

The calling user needs the velocity.pool.assign permission on the target group

Request:

{
    "gid": "<GID>",
    "mpid": "<MPID>",
    "quota": "<Quota in Bytes>",
    "write": true,
    "manage": true
}

Response:

  • 200: OK

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The gid or mpid has not been found

/m/pool/assign - DELETE

Revoke a group's permissions from a mediapool

Note

The calling user needs the velocity.pool.revoke permission on the target group

Request:

{
    "gid": "<GID>",
    "mpid": "<MPID>"
}

Response:

  • 200: OK

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The gid or mpid has not been found

/m/pool/list - POST

List back available pools for a group

Note

The calling user needs the velocity.pool.list permission on the target group

Request:

{
    "gid": "<GID>"
}

Response:

  • 200
{
    "pools": [
        {
            "mpid": "<MPID>",
            "name": "<Pool name>",
            "write": true,
            "manage": true,
        }
    ]
}

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The gid has not been found

Media management

/m/media/create - PUT

Allocate new media on a pool (pid) owned by a group (gid)

Note

The calling user needs the velocity.media.create permission on the target group

Request:

{
    "mpid": "<MPID>",
    "gid": "<GID>",
    "name": "<Media name>",
    "type": "<Media type>",
    "size": "<Size in Bytes>"
}

Response:

  • 200: Media created
{
    "mid": "<MID>",
    "size": "<Size in Bytes>"
}

  • 403 - Forbidden: The calling user lacks permissions or the group does not have the manage permission on the pool

  • 404 - Not Found: The gid or pid has not been found

  • 406 - Not Acceptable: Some quota has been surpassed

  • 409 - Conflict: A file with the same name does already exist in this pool

/m/media/upload - PUT

In contrast to the whole rest of the Velocity API, uploads are handled uniquely: Using HTTP headers to describe and authenticate the upload.

Request:

  • HTTP Additional HTTP Headers:

    • Content-Length: The amount of bytes to be submitted. The server will not accept any more bytes than specified here

    • x-velocity-mpid: The mediapool id (MPID)

    • x-velocity-gid: The group id (GID)

    • x-velocity-name: The name of the file

    • x-velocity-type: The type of file

    • x-velocity-readonly: If the file should be read only or not (true or false)

  • body: The binary data for the file

Response:

  • 200: Media uploaded
{
    "mid": "<MID>",
    "size": "<Size in Bytes>"
}

  • 400 - Bad Request: The http header is missing required fields

  • 403 - Forbidden: The calling user lacks permissions or the group does not have the manage permission on the pool

  • 404 - Not Found: The gid or pid has not been found

  • 406 - Not Acceptable: Some quota has been surpassed

  • 413 - Payload Too Large: The promised Content-Length has been surpassed

/m/media - DELETE

Remove media (delete it)

Note

The calling user needs the velocity.media.remove permission

Request:

{
    "mid": "<MID>"
}

Response:

  • 200: Media removed

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The mid has not been found

/m/media/list - POST

List back available media to a group

Note

The calling user needs the velocity.media.list permission on the target group

Request:

{
    "gid": "<GID>"
}

Response:

  • 200
{
    "media": [
        {
            "mid": "<MID>",
            "mpid": "<MPID>",
            "name": "<Media name>",
            "type": "<Media type>",
            "size": "<Size in Bytes>",
            "readonly": true
        }
    ]
}

The readonly flag is also true if the group does not have the write permission on the pool

  • 403 - Forbidden: THe calling user lacks permissions

  • 404 - Not Found: The gid has not been found

Virtual machine management

Velocity's main purpose is to manage virtual machines. This is the place for that.

A word about NICs

Network devices are a tricky thing, especially bridge devices. Velocity gives the job of assigning host nics to the administrator. As with media pools, the administrator is responsible for providing a stable NICID that the virtual NICs can use if they operate in BRIDGE mode.

VM states

A virtual machine can be in one of the following states:

  • STOPPED: The virtual machine is not running

  • STARTING: The virtual machine is moving to the RUNNING state (hypervisor)

  • RUNNING: The virtual machine is running

  • PAUSING: The virtual machine is moving to the PAUSED state (hypervisor)

  • PAUSED: The virtual machine is paused and waiting for resume

  • RESUMING: The virtual machine is moving back to the RUNNING state after being in the PAUSED state (hypervisor)

  • STOPPING: The virtual machine is moving to the STOPPED state (hypervisor)

A user can request state changes from the server, but can only transition to those that are not marked with (hypervisor).

Available endpoints

Virtual machine management

NIC management

Virtual machine management

/v/vm/list - POST

List all available virtual machines for a group

Note

The calling user needs the velocity.vm.view permission on the target group

Request:

{
  "authkey": "<authkey>",
  "gid": "<GID>",
}

Response:

  • 200:
{
  "vms": [
    {
      "vmid": "<VMID>",
      "name": "<Name>",
      "cpus": "<CPU count>",
      "memory_mib": "<Memory in MiB>",
      "state": "<VM state>"
    }
  ]
}

  • 401 - Unauthorized: The calling user lacks permissions

  • 404 - Not Found: The GID couldn't be found

/v/vm - POST

Retrieve information about a virtual machine

Note

The calling user needs the velocity.vm.view permission on the group owning the VM

Request:

{
    "authkey": "<authkey>",
    "vmid": "<VMID>"
}

Response:

  • 200:
{
  "vmid": "<VMID>",
  "name": "<VM name>",
  "type": "<EFI/...>",
  "state": "<VM state>",

  "cpus": "<Amount of CPUs assigned>",
  "memory_mib": "<Memory size in MiB>",

  "displays": [
    {
      "name": "<Friendly name>",
      "width": "<Screen width>",
      "height": "<Screen height>",
      "ppi": "<Pixels per inch>"
    }
  ],
  "media": [
    {
      "mid": "<MID>",
      "mode": "<USB / BLOCK / VIRTIO>",
      "readonly": true
    }
  ],
  "nics": [
    {
      "type": "<NAT / BRIDGE>",
      "host": "<Host NICID (BRIDGE only)>"
    }
  ],

  "rosetta": true,
  "autostart": true
}
  • 404 - Not Found: The VMID couldn't be found or the user lacks permissions to view the vm

/v/vm/efi - PUT

Create a new virtual machineCreate a new EFI virtual machine using the supplied data

Note

The calling user needs the velocity.vm.create permission on the target group

Request:

{
  "name": "<VM name>",
  "gid": "<GID>",

  "cpus": "<Amount of CPUs assigned>",
  "memory_mib": "<Memory size in MiB>",
  "displays": [
    {
      "name": "<Friendly name>",
      "width": "<Screen width>",
      "height": "<Screen height>",
      "ppi": "<Pixels per inch>"
    }
  ],
  "media": [
    {
      "mid": "<MID>",
      "mode": "<USB / BLOCK / VIRTIO>",
      "readonly": true
    }
  ],
  "nics": [
    {
      "type": "<NAT / BRIDGE>",
      "host": "<Host NICID (BRIDGE only)>"
    }
  ],

  "rosetta": true,
  "autostart": true
}

Field descriptions:

  • name: A unique name in the group to identify this virtual machine

  • gid: The group this vm belongs to

  • cpus: The amount of virtual CPUs that should be available to the guest

  • memory_mib: The amount of memory assigned to the guest in MiB

  • displays: An array of displays

    • description: A way if identifying this display

    • width: The width in px

    • height: The height in px

  • media: An array of attached media devices

    • mid: The MID of the media to attach

    • mode: The mode the device should use:

      • USB: The media is attached via USB

      • BLOCK: The VZVirtioBlockDeviceConfiguration is used to emulate a block device

      • VIRTIO: Use VirtIO for device attachment

    • readonly: Block writing to the media, if not already blocked by other rules

  • nics: An array of attached network devices

    • type The type of NIC:

      • NAT: Use a NAT

      • BRIDGE: Bridge a host network device

    • host: (only needed when BRIDGE): The host device to bridge (NICID)

  • rosetta: Whether to enable the rosetta x86 translation layer if available on the host

  • autostart: Whether to automatically start this virtual machine on Velocity startup

Response:

  • 200: Virtual machine created
{
  "vmid": "<VMID>"
}

  • 401 - Unauthorized: The calling user lacks permissions

  • 404 - Not Found: A linked resource couldn't be found

  • 406 - Not Acceptable: There was a quota violation or invalid type or mode specified

  • 409 - Conflict: A virtual machine in this group with the same name does already exist

/v/vm/state - POST

Request the current vm state

Note

The calling user needs the velocity.vm.view permission on the group the vm belongs to

Request:

{
  "vmid": "<VMID>"
}

Response:

  • 200:
{
  "vmid": "<VMID>",
  "state": "<VM state>"
}

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The VMID is not available or doesn't exist

/v/vm/state - PUT

Request a state change for the virtual machine. Valid states:

  • STOPPED

  • RUNNING

  • PAUSED

Note

The calling user needs the velocity.vm.state permission on the group the vm belongs to

Request:

{
  "vmid": "<VMID>",
  "state": "<VM state>",
  "force": true
}

If the force flag is set to true state changes will be forceful (eg. shutdown being immediate instead of graceful)

Response:

  • 200: State changed. If the VM is already in the requested state, 200 will be used.
{
  "vmid": "<VMID>",
  "state": "<VM state>"
}

  • 403 - Forbidden: The calling user lacks permissions

  • 404 - Not Found: The VMID is not available to the user or doesn't exist

  • 500 - Internal Server Error: A hypervisor error occured during state transition

NIC management

/v/nic/list - POST

List all available host NICs available for BRIDGE use

Note

The calling user needs the velocity.nic.list permission somewhere

Request:

<NO BODY>

Response:

{
  "host_nics": [
    {
      "nicid": "<NICID>",
      "description": "<Host OS description>",
      "identifier": "<Host OS identifier>"
    }
  ]
}