API: Virtual machines

Create, list and control VMs: start, stop, reboot, resize, reinstall, restore, delete and console.

A VM is called an order in the API. Actions are asynchronous: they answer 202 straight away with the VM in a working status, and you poll GET /orders/{order} until it settles. See API conventions.

List your VMs

GET /orders

Returns your VMs, optionally filtered by status.

Authentication: Send your API key or token as a bearer token.

Query parameters

Field	Type	Values
`status`	string	`pending`, `provisioning`, `running`, `failed`, `deleting`, `resizing`, `reinstalling`, `terminated`, `stopped`, `starting`, `stopping`, `rebooting`, `restoring`
`per_page`	integer

Responses

200 OK. Returns: data (list of Order).

Example

curl -X GET https://veneshcloud.ir/api/orders \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Create a VM

POST /orders

Orders a VM on a plan. The first month is charged from your wallet. If the wallet cannot cover the required minimum, the request is rejected and the error states the requirement. The VM is built in the background.

Authentication: Send your API key or token as a bearer token.

Request body (application/json)

Field	Type	Required
`customer_plan_id`	integer	Yes
`os_image`	string	Yes
`region`	string	No
`hostname`	string	No
`ssh_public_key`	string	No
`password`	string	No
`disk_gb`	integer	No
`assign_public_ip`	boolean	No
`bandwidth_mbps`	integer	No
`open_ports`	list of integer	No
`user_data`	string	No
`description`	string	No
`assign_ipv6`	boolean	No
`data_disk_gb`	integer	No
`tags`	object	No
`join_private_network_id`	integer	No
`source_snapshot_id`	integer	No
`install_monitoring_agent`	boolean	No

Responses

200 OK. Returns Order.
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"customer_plan_id":1,"os_image":"ubuntu-22.04"}'

Get a VM

GET /orders/{order}

Returns one of your VMs and its status.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns Order.

Example

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Get console access

GET /orders/{order}/console

Returns console details for the VM. The shape depends on the provider (serial instructions or a VNC link) and links can expire within seconds, so request it just before use.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns: console (OrderConsole).
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state
502 Provider error
503 Temporarily unavailable

Example

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID/console \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Delete a VM

POST /orders/{order}/actions/delete

Terminates the VM. Allowed when it is running or failed. Not reversible.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/delete \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Resize a VM

POST /orders/{order}/actions/resize

Moves the VM to another plan on the same provider and region. The VM must be running. OVHcloud VMs cannot be shrunk.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Request body (application/json)

Field	Type	Required	Values
`customer_plan_id`	integer	Yes

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/resize \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"customer_plan_id":1}'

List resize options

GET /orders/{order}/resize-options

Returns the plans you can resize to, and the distinct vCPU and RAM values found in them, for building two independent pickers.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns ResizeOptions.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID/resize-options \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Reinstall the OS

POST /orders/{order}/actions/reinstall

Wipes the disk and installs the chosen image. The VM must be running. The plan stays the same.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Request body (application/json)

Field	Type	Required	Values
`os_image`	string	Yes

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/reinstall \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"os_image":"ubuntu-22.04"}'

Start a VM

POST /orders/{order}/actions/start

Starts a stopped VM.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/start \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Stop a VM

POST /orders/{order}/actions/stop

Stops a running VM. Its disk is kept.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/stop \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Reboot a VM

POST /orders/{order}/actions/reboot

Reboots a running VM.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/reboot \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Restore from a snapshot

POST /orders/{order}/actions/restore

Overwrites the VM's disk with one of its own completed snapshots. The VM must be running or stopped. Not reversible.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Request body (application/json)

Field	Type	Required	Values
`snapshot_id`	integer	Yes

Responses

202 Accepted, work continues in the background. Returns Order.
403 Not allowed, the resource is not yours
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/actions/restore \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id":1}'

Renew a VM

POST /orders/{order}/renew

Pays the next 30-day period from your wallet now (plan price plus data disk). Allowed when the VM is overdue or suspended, or within 7 days of its renewal date. A VM stopped for non-payment is started again. Answers 422 with a readable message if the balance is too low.

Authentication: Send your API key or token as a bearer token.

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns: data (Order).
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/renew \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Objects

Field lists for the objects returned above.

CustomerPlan

Field	Type	Values
`id`	integer
`name`	string
`provider`	string
`plan_name`	string
`region`	string
`os_options`	list of string
`specs`	object
`usd_equivalent_price`	string
`rial_price`	integer
`fx`	object
`active`	boolean

Order

Field	Type	Values
`billing`	`OrderBilling`
`id`	integer
`status`	string	`pending`, `provisioning`, `running`, `failed`, `deleting`, `resizing`, `reinstalling`, `terminated`, `stopped`, `starting`, `stopping`, `rebooting`, `restoring`
`customer_plan`	`CustomerPlan`
`region`	string
`os_image`	string
`hostname`	string
`price_usd`	string
`price_rial`	integer
`external_instance_id`	string
`failure_reason`	string
`source_snapshot_id`	integer
`ipv4_address`	string
`ipv6_address`	string
`has_live_instance`	boolean
`created_at`	string
`provisioned_at`	string

OrderBilling

Field	Type	Values
`state`	string	`active`, `overdue`, `suspended`
`paid_until`	string
`next_renewal_at`	string
`suspended_at`	string
`renewal_price_usd`	string
`renewal_price_rial`	integer
`data_disk_gb`	integer
`auto_renew`	boolean
`daily_accrual_usd`	string
`daily_accrual_rial`	integer
`wallet_balance_rial`	integer
`delete_at_balance_rial`	integer
`rial_until_deletion`	integer
`wallet_balance_usd`	string
`delete_at_balance_usd`	number
`usd_until_deletion`	number

ResizeOptions

Field	Type	Values
`provider`	string
`region`	string
`current`	object
`cpu_options`	list of integer
`ram_options`	list of integer
`plans`	list of object