Build virtual machine

POST 
/organizations/organization/virtual_machines/build

Builds a new virtual machine based on the arguments provided to this endpoint. Virtual machines will be built in the background. This task will return an task object that will allow you to monitor the build process using the appropriate API action. This action only offers a small subset of the full functionality needed when provisioning virtual machines - see the build_from_spec action for a full advanced virtual machine creation method.

Scopes

• virtual_machines

OAuth2 Scopes

When using OAuth2 authentication, scopes are prefixed with api.katapult.io/core/v1/.

Request

application/json

Body

organization

object

required

All 'organization[]' params are mutually exclusive, only one can be provided.

id string

sub_domain string

zone

object

All 'zone[]' params are mutually exclusive, only one can be provided.

id string

permalink string

data_center

object

All 'data_center[]' params are mutually exclusive, only one can be provided.

id string

permalink string

package

object

required

All 'virtual_machine_package[]' params are mutually exclusive, only one can be provided.

id string

permalink string

disk_template

object

All 'disk_template[]' params are mutually exclusive, only one can be provided.

id string

permalink string

disk_template_options

object[]

Array [

key stringrequired

value string

]

disks

object[]

Array [

name string

size_in_gb integerrequired

initial_file_system FileSystemEnum (string)

Possible values: [ext4, xfs]

system boolean

Default false. Exactly one disk must be marked as the system disk

io_profile

object

All 'io_profile[]' params are mutually exclusive, only one can be provided.

id string

permalink string

storage_speed StorageSpeedEnum (string)

Possible values: [nvme, ssd]

]

network

object

All 'network[]' params are mutually exclusive, only one can be provided.

id string

permalink string
hostname string

annotations

object[]

Array [

key stringrequired

value string

]

Responses

201

Builds a new virtual machine based on the arguments provided to this endpoint. Virtual machines will be built in the background. This task will return an task object that will allow you to monitor the build process using the appropriate API action. This action only offers a small subset of the full functionality needed when provisioning virtual machines - see the build_from_spec action for a full advanced virtual machine creation method.

application/json

Schema

Schema

task

object

required

id string

name string

status TaskStatusEnum (string)

Possible values: [pending, running, completed, failed]

build

object

required

id string

state VirtualMachineBuildStateEnum (string)

Possible values: [draft, failed, pending, complete, building]

virtual_machine_build

object

required

id string

state VirtualMachineBuildStateEnum (string)

Possible values: [draft, failed, pending, complete, building]

hostname stringrequired

annotations

object[]

required

Array [

key stringrequired

value string

]

Example (from schema)

{
  "task": {
    "id": "string",
    "name": "string",
    "status": "pending"
  },
  "build": {
    "id": "string",
    "state": "draft"
  },
  "virtual_machine_build": {
    "id": "string",
    "state": "draft"
  },
  "hostname": "string",
  "annotations": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

400

No API token was provided in the Authorization header. Ensure a token is provided prefixed with Bearer

application/json

Schema

Schema

code MissingAPITokenEnum (string)

Possible values: [missing_api_token]

description string
detail object

Example (from schema)

{
  "code": "missing_api_token",
  "description": "string",
  "detail": {}
}

403

403 error response

application/json

Schema

Schema

oneOf

UnauthorizedNetworkForAPITokenSchema

Network is not allowed to access the API with this API token

code UnauthorizedNetworkForAPITokenEnum (string)

Possible values: [unauthorized_network_for_api_token]

description string

detail

object

ip_address string

The IP address the request was received from

InvalidAPITokenSchema

The API token provided was not valid (it may not exist or have expired)

code InvalidAPITokenEnum (string)

Possible values: [invalid_api_token]

description string

detail

object

details stringnullable

InvalidCapabilitiesTokenSchema

The capabilities token provided was not valid (either not valid, expired or not signed by the correct key)

code InvalidCapabilitiesTokenEnum (string)

Possible values: [invalid_capabilities_token]

description string

detail object

ScopeNotGrantedErrorSchema

The scope required for this endpoint has not been granted to the authenticating identity

code ScopeNotGrantedErrorEnum (string)

Possible values: [scope_not_granted]

description string

detail

ScopeNotGrantedError

scopes string[]

OrganizationSuspendedSchema

An organization was found from the arguments provided but it was suspended

code OrganizationSuspendedEnum (string)

Possible values: [organization_suspended]

description string

detail object

OrganizationNotActivatedSchema

An organization was found from the arguments provided but it wasn't activated yet

code OrganizationNotActivatedEnum (string)

Possible values: [organization_not_activated]

description string

detail object

PermissionDeniedSchema

The authenticated identity is not permitted to perform this action

code PermissionDeniedEnum (string)

Possible values: [permission_denied]

description string

detail

object

details stringnullable

Additional information regarding the reason why permission was denied

ResourceCreationRestrictedSchema

The organization chosen is not permitted to create resources

code ResourceCreationRestrictedEnum (string)

Possible values: [resource_creation_restricted]

description string

detail

ResourceCreationRestricted

errors string[]

Example (from schema)

{}

404

404 error response

application/json

Schema

Schema

oneOf

OrganizationNotFoundSchema

No organization was found matching any of the criteria provided in the arguments

code OrganizationNotFoundEnum (string)

Possible values: [organization_not_found]

description string

detail object

ZoneNotFoundSchema

No zone was found matching any of the criteria provided in the arguments

code ZoneNotFoundEnum (string)

Possible values: [zone_not_found]

description string

detail object

DataCenterNotFoundSchema

No data center was found matching any of the criteria provided in the arguments

code DataCenterNotFoundEnum (string)

Possible values: [data_center_not_found]

description string

detail object

VirtualMachinePackageNotFoundSchema

No package was found matching any of the criteria provided in the arguments

code VirtualMachinePackageNotFoundEnum (string)

Possible values: [package_not_found]

description string

detail object

DiskTemplateNotFoundSchema

No disk template was found matching any of the criteria provided in the arguments

code DiskTemplateNotFoundEnum (string)

Possible values: [disk_template_not_found]

description string

detail object

NetworkNotFoundSchema

No network was found matching any of the criteria provided in the arguments

code NetworkNotFoundEnum (string)

Possible values: [network_not_found]

description string

detail object

Example (from schema)

{}

422

422 error response

application/json

Schema

Schema

oneOf

ValidationErrorSchema

A validation error occurred with the object that was being created/updated/deleted

code ValidationErrorEnum (string)

Possible values: [validation_error]

description string

detail

ValidationError

errors string[]

LocationRequiredSchema

A zone or a data_center argument must be provided

code LocationRequiredEnum (string)

Possible values: [location_required]

description string

detail object

OneSystemDiskRequiredSchema

Exactly one disk must be marked as the system disk

code OneSystemDiskRequiredEnum (string)

Possible values: [one_system_disk_required]

description string

detail object

Example (from schema)

{}

429

You have reached the rate limit for this type of request

application/json

Schema

Schema

code RateLimitReachedEnum (string)

Possible values: [rate_limit_reached]

description string

detail

object

total_permitted integer

The total number of requests per minute that are permitted

Example (from schema)

{
  "code": "rate_limit_reached",
  "description": "string",
  "detail": {
    "total_permitted": 0
  }
}

503

The service is currently unavailable, please try again later

application/json

Schema

Schema

code ServiceUnavailableEnum (string)

Possible values: [service_unavailable]

description string
detail object

Example (from schema)

{
  "code": "service_unavailable",
  "description": "string",
  "detail": {}
}

Loading...