tiCrypt REST API

tiCrypt Token API Usage and Routes

Usage

The tiCrypt API exposed to the generated tokens is based off the token type generated, e.g. Drive tokens can only access Drive Routes, VM tokens can only access VM Routes, Team tokens can only access Team Routes, and Project tokens can only access Project Routes. The tokens may be read in one of two ways: through the token URL parameter, or via the TC_TOKEN cookie in the header.

Note that the token may be specified in either the URL Parameters OR the cookie. In the case that both are defined, it will take the token in the URL Parameter and ignore the cookie token.

Drive Routes

Summary of Routes

Route	Method	Description
`/api/drives`	`GET`	Get Drives

Get Drives

GET /api/drives

Lists all drives on the system. On success, a list of the following object is returned:

interface DriveInfo {
  id: string; // Drive ID
  name: string; // Name of the drive
  owner: string; // ID of the user who owns the drive
  capacity: number; // Total capacity in bytes
  format: string; // Drive format (ext4, ntfs, etc.)
  noBackup?: boolean; // Defaults to true; whether or not a drive has backup enabled or not (Deprecated)
  settings?: object; // JSON settings that the frontend uses
  writer?: string; // ID of any VM this drive has attached as read-write
  readers: string[]; // ID of any VMs this drive has attached as read-only
  created: number; // Epoch time in millis, when the drive was created
  changed?: number; // Epoch time in millis, when the drive was last modified
  attached?: number; // Epoch time in millis, when the drive was last attached
  writable?: boolean; // Whether or not the drive can be written to or not
  poolID?: string; // Optional, the ID of the libvirt pool if it is not stored in the libvirt pool
  team?: string; // ID of the team that owns this drive
  project?: string; // ID of the project this drive is tagged under
  realmID: string; // Realm the drive is under
  diskType?: string; // qcow2 / raw / etc.
  cache?: string; // Drive cache option
  io?: string; // Drive io option
  state: string; // State of the drive: Ready / ReadOnly / ReadWrite / Transferring / Initializing
  stateChange?: number; // Epoch time in millis, when the drive's state last changed
  hasSnapshot: boolean; // Whether or not the drive still has snapshots in system
}

In JSON:

{
  "id": "string",
  "name": "string",
  "owner": "string",
  "capacity": "number",
  "format": "string",
  "noBackup": "boolean",
  "settings": "object",
  "writer": "string",
  "readers": ["string"],
  "created": "number",
  "changed": "number",
  "attached": "number",
  "writable": "boolean",
  "poolID": "string",
  "team": "string",
  "project": "string",
  "realmID": "string",
  "diskType": "string",
  "cache": "string",
  "io": "string",
  "state": "string",
  "stateChange": "number",
  "hasSnapshot": "boolean"
}

VM Routes

Summary of Routes

Route	Method	Description
`/api/vms/images`	`GET`	Get VM Images
	`POST`	Create VM Image
`/api/vms/bricks`	`PATCH`	Edit Brick(Hardware Setup)

Get VM Images

GET /api/vms/images[&token=<token>]

Request Body:

{
  "realm": "<realmID>"
}

CURL Request Example:

  curl --request POST \
    --url 'https://api-demo.ticrypt.com/api/vms/images[?token=1VtLip1Wb85S6ttHTuwbbzsI3mAOpe58]' \
    --header 'Content-Type: application/json' \
    --header 'TC_TOKEN: 1VtLip1Wb85S6ttHTuwbbzsI3mAOpe58' \
    --data '{"realm": "libvirt"}'

Lists all of the images for the realm specified in the body. On success, a list of the following object is returned:

interface ImageInfo {
  id:           string; //ID of the image
  name?:        string; //Optional name
  description?: string; //Optional text description
  size?:        number; //Size of the image in bytes
  imageType?:   string; //Optional image type: "windows" | "linux"
  info:         LibvirtExtraInfo | NutanixExtraInfo; // Info related to the image, see below for details
  created?:     timestamp; //Time of creation
  modified?:    timestamp; //Time of last modification
  version?:     number; //Empty if it's the base image, e.g. ver. 0
  parent?:      string; //Empty if it's the base image
  limit?:       number; //Optional, number of VMs that may be launched under this image at once     
                              //(Undefined = no limit)
  settings?:    json; //Optional, tiCrypt frontend-only settings for this image
}

LibvirtExtraInfo

interface LibvirtExtraInfo {
  pool:     string; //poolID
  volume:   string; //the volume's name in the pool e.g. my-image.img
  deviceBusType: "scsi" | "virtio";
}

NutanixExtraInfo

interface NutanixExtraInfo {
  sourceType:   "NDFS" | "VolumeGroup" | "VMDisk";
  timezone?:    string;
}

In json:

{
  "id": "string",
  "name": "string",
  "description": "string",
  "size": "number",
  "imageType": "string",
  "info": {
    "pool": "string",
    "volume": "string",
    "deviceBusType": "scsi | virtio"
  },
  "created": "timestamp",
  "modified": "timestamp",
  "version": "number",
  "parent": "string",
  "limit": "number",
  "settings": "json"
}

Create VM Image

POST /api/vm/images[&token=<token>]

Request Body:

Field	Type	Description
realm	String	Realm ID for the image
name?	String	A name for the image
description?	String	Short description for the image
size?	number	Image's size in bytes
imageType?	String	The image type (windows
info	LibvirtExtraInfo or NutanixExtraInfo	A structure containing realm-specific information
limit?	number	The number of VMs this image can be used for at once

{
  "realm": "string",
  "name": "string",
  "description": "string",
  "size": "number",
  "imageType": "windows | linux",
  "info": {
    "pool": "string",
    "volume": "string",
    "deviceBusType": "scsi | virtio"
  },
  "limit": "number"
}

CURL Request Example

  curl --request POST \
    --url 'https://api-demo.ticrypt.com/api/vm/images[?token=1VtLip1Wb85S6ttHTuwbbzsI3mAOpe58]' \
    --header 'Content-Type: application/json' \
    --header 'TC_TOKEN: 1VtLip1Wb85S6ttHTuwbbzsI3mAOpe58' \
    --data '{
    "realm": "libvirt",
    "name": "newImage",
    "description": "My new image",
    "size": 5368709120,
    "imageType": "linux",
    "info": {
      "pool": "ticrypt-vm-drives",
      "volume": "rocky8-prod.qcow2",
      "deviceBusType": "virtio"
    },
    "limit": 5
  }'

Creates a new VM image. Returns the following on success:

interface ImageInfo {
  id:           string; //ID of the image
  name?:        string; //Optional name
  description?: string; //Optional text description
  size?:        number; //Size of the image in bytes
  imageType?:   string; //Optional image type: "windows" | "linux"
  info:         LibvirtExtraInfo | NutanixExtraInfo; // Info related to the image, see below for details
  created?:     timestamp; //Time of creation
  modified?:    timestamp; //Time of last modification
  version?:     number; //Empty if it's the base image, e.g. ver. 0
  parent?:      string; //Empty if it's the base image
  limit?:       number; //Optional, number of VMs that may be launched under this image at once     
                              //(Undefined = no limit)
  settings?:    json; //Optional, tiCrypt frontend-only settings for this image
}

In json:

{
  "id": "string",
  "name": "string",
  "description": "string",
  "size": "number",
  "imageType": "string",
  "info": {
    "pool": "string",
    "volume": "string",
    "deviceBusType": "scsi | virtio"
  },
  "created": "timestamp",
  "modified": "timestamp",
  "version": "number",
  "parent": "string",
  "limit": "number",
  "settings": "json"
}

Edit Brick

PATCH /api/vm/bricks[&token=<token>]

Request Body: | Name | Type | Description | |-----------------|-----------------------|-----------------------------------------------------------------------------| | brick | string | The ID of the brick to be edited | | params | BrickParameters | The parameters to edit; only the fields that are defined will be changed |

Brick Update Parameters

Name	Type	Description
`name`	`string`	Short, user-specified name for the brick.
`description`	`string`	Longer form, possibly markdown description for the brick.
`vcores`	`number`	Number of virtual CPU cores to be used by VMs with this brick.
`maxMemBytes`	`number`	RAM used by VMs with this brick, in bytes.
`setup`	`string`	Descriptions for Brick Setup for when it gets used to create a VM
`realmID`	`string`	ID of realm on which this Brick will be defined.
`libvirt?`	`LibvirtBrickConfig`	Libvirt-specific brick configuration information. Required if the realm's driver type is 'libvirt'.
`nutanix?`	`NutanixBrickSpec`	Nutanix-specific info to get its configuration information. Required if the realm's driver type is 'nutanix'.
`whitelist?`	`BrickWhitelist`	Optional. Whitelist containing those allowed to access the brick.
`externalServers?`	`string[]`	Optional. The list of external servers the brick can access.
`format?`	`string`	Optional. Brick OS format, currently supporting Linux or Windows.

In json:

{
  "id": "string",
  "params": {
    "name": "string",
    "description": "string",
    "vcores": "number",
    "maxMemBytes": "number",
    "setup": "string",
    "realmID": "string",
    "libvirt": {
      // Libvirt-specific brick configuration information
        "image": {
          // Location of disk image containing the operating system.
          "pool": "string",
          "volume": "string"
        },
        "video": "vnc | spice", // Type of video device to attach to VM, if any. Default: none.
        "pty": "boolean", // Whether to attach a terminal to the VM. Default: false.
        "clockOffset": "utc | localtime", // Offset to use for VM clock. Default: 'localtime' for Windows, 'utc' for others.
        "nic": "string", // Type of virtual network card to attach to the VM. Default: virtio. Additional options: rtl8139.
        "devices": {
          // Mapping of device type to number required. Default: empty.
        },
        "extraXML": "string", // Optional. Additional XML configuration.
        "headfullGPU": "string", // Optional. GPU configuration for headfull VMs.
        "deviceBusType": "string" // Optional. Type of device bus.
    },
    "nutanix": {
      // Nutanix-specific info to get its configuration information
      "imageID": "string", // ID used to access the underlying Nutanix VM
      "timezone": "string", // Optional. Timezone in which to present the clock to the VM. Default: none
      "devices": { // Optional. A map between the GPU type and the number of them needed
        "deviceType": "number"
      },
      "osType": "string", // Optional. Used to determine the brick's VM type: 'linux' or 'windows'
      "debug": "boolean" // Optional. Flag for the VM Config, set true if VM is to be debugged
    },
    "whitelist": {
      "teamIDs": ["string"],
      "userIDs": ["string"]
    },
    "externalServers": ["string"],
    "format": "string"
  }
}

CURL Request:

  curl --request PATCH \
    --url 'https://api-demo.ticrypt.com/api/vms/bricks[?token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
    --header 'Content-Type: application/json' \
    --header 'TC_TOKEN: 1VtLip1Wb85S6ttHTuwbbzsI3mAOpe58' \
    --data '{
    "id": "brickID",
    "params": {
      "name": "New Brick Name",
      "description": "My updated brick",
      "vcores": "1",
      "maxMemBytes": "5368709120",
      "setup": "These are instructions to set up the VM...",
      "realmID": "libvirt",
      "libvirt": {
          "image": {
            "pool": "ticrypt-vm-drives",
            "volume": "new-volume.qcow2"
          },
          "video": "vnc",
          "pty": true,
          "clockOffset": "localtime",
          "nic": "virtio",
          "devices": {
            "gpu-nvidia": 1
          },
          "extraXML": "<body></body>",
          "deviceBusType": "scsi"
      },
      "whitelist": {
        "teamIDs": ["team1"],
        "userIDs": ["user1", "user2"]
      },
      "externalServers": ["server1"],
      "format": "linux"
    }
  }'

Creates a Hardware Setup for use in creating VMs. On success, returns the following:

interface BrickInfo {
  id: string;     // Unique identifier
  name: string;   // User-specified name
  description: string;  // Longer-form description
  setup?: string;       // Markdown setup instructions
  vcores: number;       // number of virtual CPU cores used by the brick
  maxMemBytes: number;  // amount of memory in bytes used by the brick
  realmID: string;      // Realm to which this brick belongs.
  /**
   * Libvirt-specific brick configuration information.
   * Required if the realm's driver type is 'libvirt'.
   */
  libvirt?: LibvirtBrickConfig;
  /*
   * Nutanix-specific info to get its configuration information.
   * Required if the realm's driver type is 'nutanix'.
   */
  nutanix?: NutanixBrickConfig;
  // Teams and users allowed to access the brick. If not specified, the brick is
  // publically accessible.
  whitelist?: BrickWhitelist;
  creatorID: string;    // ID of user that created the brick.
  externalServers: string[]; // List of external servers the brick can access
  format?: string     //Brick OS format, currently supporting Linux or Windows
  imageID?: string    //ID that corresponds to an image
  created: Instant;   // Time the brick was created
  modified: Instant?  // Time the brick was last modified
  noQuota: Boolean;   // Whether or not the brick is tagged for team quotas, default: false
  params?: string;    //Optional parameters to give to the VM
  settings? string;   //Optional frontend-only settings for this brick
  vmType: 'Secure' | 'Service' | 'Data' | 'Worker'; //The VM Type for the brick
}

{
  "id": "string", // Unique identifier
  "name": "string", // User-specified name
  "description": "string", // Longer-form description
  "setup": "string", // Markdown setup instructions
  "vcores": "number", // Number of virtual CPU cores used by the brick
  "maxMemBytes": "number", // Amount of memory in bytes used by the brick
  "realmID": "string", // Realm to which this brick belongs
  "libvirt": {
    "image": {
      "pool": "string", // Location of disk image pool
      "volume": "string" // Volume name in the pool
    },
    "video": "vnc | spice", // Type of video device to attach to VM
    "pty": "boolean", // Whether to attach a terminal to the VM
    "clockOffset": "utc | localtime", // Offset to use for VM clock
    "nic": "string", // Type of virtual network card to attach to the VM
    "devices": {
      "deviceType": "number" // Mapping of device type to number required
    },
    "extraXML": "string", // Additional XML configuration
    "headfullGPU": "string", // GPU configuration for headfull VMs
    "deviceBusType": "string" // Type of device bus
  },
  "nutanix": {
    "imageID": "string", // ID used to access the underlying Nutanix VM
    "timezone": "string", // Timezone for the VM clock
    "devices": {
      "deviceType": "number" // Mapping of device type to number required
    },
    "osType": "string", // VM type: 'linux' or 'windows'
    "debug": "boolean" // Flag for VM debugging
  },
  "whitelist": {
    "teamIDs": ["string"], // Teams allowed to access the brick
    "userIDs": ["string"] // Users allowed to access the brick
  },
  "externalServers": ["string"], // List of external servers the brick can access
  "format": "string", // Brick OS format, e.g., Linux or Windows
  "imageID": "string", // ID that corresponds to an image
  "created": "timestamp", // Time the brick was created
  "modified": "timestamp", // Time the brick was last modified
  "noQuota": "boolean", // Whether the brick is tagged for team quotas
  "params": "string", // Optional parameters for the VM
  "settings": "string", // Frontend-only settings for this brick
  "vmType": "Secure | Service | Data | Worker" // The VM Type for the brick
}

Team Routes

Structures

TeamInfo

interface TeamInfo {
  id: string; // Unique identifier for the team
  name: string; // User-given name for the team
  desc: string; // User-given description for the team
  created: datetime; // Instant at which the team was created
  modified: datetime; // Instant at which the metadata was last modified
  quotas: { [key: string]: number }; // Old representation of quotas for the team. Mapping of string -> int
  teamQuotas: QuotasTyped; // Shaped version of quotas for the team
  perUserQuotas: QuotasTyped; // Shaped version of quotas per user
  settings: object; // JSON object. Team-wide settings
  startDate?: datetime; // Denotes the time at which the team can access resources
  endDate?: datetime; // Denotes the time at which the team can no longer access resources
}

interface QuotasTyped {
  cores?: number; // Number of cores. Optional (None denotes no limit)
  memory?: number; // Amount of memory, in bytes. Optional (None denotes no limit)
  storage?: { [storageType: string]: number }; // (storageType -> size, in bytes) Optional (Defaults to empty map, which denotes no limits on any type)
  devices?: { [deviceType: string]: number }; // (deviceType -> number of devices) Optional (Defaults to empty map, which denotes no limits on any type)
}

In JSON:

{
  "id": "string",
  "name": "string",
  "desc": "string",
  "created": "datetime",
  "modified": "datetime",
  "quotas": {
    "resourceType": "number"
  },
  "teamQuotas": {
    "cores": "number",
    "memory": "number",
    "storage": {
      "storageType": "number"
    },
    "devices": {
      "deviceType": "number"
    }
  },
  "perUserQuotas": {
    "cores": "number",
    "memory": "number",
    "storage": {
      "storageType": "number"
    },
    "devices": {
      "deviceType": "number"
    }
  },
  "settings": {},
  "startDate": "datetime",
  "endDate": "datetime"
}

Route Summary

Route	Method	Description
`/api/teams`	`GET`	Get Teams
	`POST`	Create Team
`/api/teams/quotas`	`GET`	Get Team Quotas
	`PATCH`	Edit Team Quotas

Get Teams

GET /api/teams[&token=<token>]

There is no body for this request.

CURL Request Example:

curl --request GET \
  --url 'https://api-demo.ticrypt.com/api/teams[?token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
  --header 'TC_TOKEN=RK20CusLkydNpopRXpHWGBIf81u5XAl8'

Returns all teams on the system. On success, responds with a list of TeamInfo.

Create Team

POST /api/teams[&token=<token>]

Request Body:

Attribute	Type	Description
name	string	Name of the team
desc	string	Description of the team

{
  "name": "string",
  "desc": "string"
}

CURL Request Example

curl --request POST \
  --url 'https://api-demo.ticrypt.com/api/teams[?token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
  --header 'Content-Type: application/json' \
  --header 'TC_TOKEN=RK20CusLkydNpopRXpHWGBIf81u5XAl8' \
  --data '{
    "name": "New Team",
    "desc": "Description of the new team"
  }'

Creates a new team. On success, responds with the newly created team's TeamInfo.

Get Team Quotas

GET /api/teams/quotas[&token=<token>]

Request Body:

{
  "teamID": "string"
}

CURL Request Example

curl --request GET \
  --url 'https://api-demo.ticrypt.com/api/teams/quotas[?token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
  --header 'Content-Type: application/json' \
  --header 'TC_TOKEN=RK20CusLkydNpopRXpHWGBIf81u5XAl8' \
  --data '{
    "teamID": "teamID"
  }'

Returns the quotas for a specific team. On success, responds with the team's QuotasTyped.

Edit Team Quotas

PATCH /api/teams/quotas[&token=<token>]

Request Body:

Attribute	Type	Description
teamID	string	ID of the team
quotas	QuotasTyped	New quotas for the team

{
  "teamID": "string",
  "quotas": {
    "cores": "number",
    "memory": "number",
    "storage": {
      "storageType": "number"
    },
    "devices": {
      "deviceType": "number"
    }
  }
}

CURL Request Example

curl --request PATCH \
  --url 'https://api-demo.ticrypt.com/api/teams/quotas[?token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
  --header 'Content-Type: application/json' \
  --header 'TC_TOKEN=RK20CusLkydNpopRXpHWGBIf81u5XAl8' \
  --data '{
    "teamID": "teamID",
    "quotas": {
      "cores": 10,
      "memory": 10737418240,
      "storage": {
        "vault": 53687091200,
        "drives": 107374182400
      },
      "devices": {
        "gpu-nvidia": 2
      }
    }
  }'

Updates the quotas for a specific team. On success, responds with the updated TeamInfo.

Project Routes

Project Structures

ProjectInfo

Attribute	Type	Description
id	string	Unique ID for the project
name	string	Short name
desc	string	Longer form description, possibly markdown
securityLevel	string	ID of security level required to access this project
parent	string?	ID of parent project, if this is a sub-project
settings	object	Additonal settings available to frontend, no required structure past being a valid JSON object
created	datetime	Date and time at which project was created
modified	datetime	Date and time at which project metatdata was last modified

In JSON:

{
  "id": "string",
  "name": "string",
  "desc": "string",
  "securityLevel": "string",
  "parent": "string",
  "settings": {},
  "created": "datetime",
  "modified": "datetime"
}

Summary of Routes

Route	Method	Description
`/api/projects`	`GET`	Get Projects
`/api/projects/<projectID>`	`GET`	Get Project

Get Projects

GET /api/projects[&token=<token>]

There is no body for this request.

CURL Request Example

curl --request GET \
  --url 'https://api-demo.ticrypt.com/api/projects[?token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
  --header 'TC_TOKEN=RK20CusLkydNpopRXpHWGBIf81u5XAl8'

Returns all projects on the system. On success, responds with a list of project information.

Get Project

GET /api/projects/<projectID>[&token=<token>]

There is no body for this request.

CURL Request Example for Get Project

curl --request GET \
  --url 'https://api-demo.ticrypt.com/api/projects/<projectID>?[token=RK20CusLkydNpopRXpHWGBIf81u5XAl8]' \
  --header 'TC_TOKEN=RK20CusLkydNpopRXpHWGBIf81u5XAl8'

Returns information about a specific project. On success, responds with the project information for the specified id.

Usage​

Drive Routes​

Summary of Routes​

Get Drives​

VM Routes​

Summary of Routes​

Get VM Images​

LibvirtExtraInfo​

NutanixExtraInfo​

Create VM Image​

CURL Request Example​

Edit Brick​

Brick Update Parameters​

Team Routes​

Structures​

TeamInfo​

Route Summary​

Get Teams​

Create Team​

CURL Request Example​

Get Team Quotas​

CURL Request Example​

Edit Team Quotas​

CURL Request Example​

Project Routes​

Project Structures​

ProjectInfo​

Summary of Routes​

Get Projects​

CURL Request Example​

Get Project​

CURL Request Example for Get Project​

Usage

Drive Routes

Summary of Routes

Get Drives

VM Routes

Summary of Routes

Get VM Images

LibvirtExtraInfo

NutanixExtraInfo

Create VM Image

CURL Request Example

Edit Brick

Brick Update Parameters

Team Routes

Structures

TeamInfo

Route Summary

Get Teams

Create Team

CURL Request Example

Get Team Quotas

CURL Request Example

Edit Team Quotas

CURL Request Example

Project Routes

Project Structures

ProjectInfo

Summary of Routes

Get Projects

CURL Request Example

Get Project

CURL Request Example for Get Project