API: Firewall, static IPs and snapshots

Per-VM firewall rules, static IPs and snapshots, plus account-wide lists.

Snapshots are taken by the provider: restore and copy only work for completed snapshots. The older firewall-rule and static-IP endpoints only keep records and are deprecated; use the firewall and floating-IP endpoints instead. See Snapshots.

List firewall rules

GET /orders/{order}/firewall-rules

Returns the rules saved for a VM.

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

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns: data (list of FirewallRule).
403 Not allowed, the resource is not yours

Example

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

Add a firewall rule

POST /orders/{order}/firewall-rules

Saves a rule for the VM. port_range is a single port like 22 or a range like 1000-2000.

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
`direction`	string	Yes	`in`, `out`
`protocol`	string	Yes	`tcp`, `udp`, `icmp`
`port_range`	string	No
`source_cidr`	string	Yes
`description`	string	No

Responses

201 Created. Returns FirewallRule.
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/firewall-rules \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"direction":"in","protocol":"tcp","source_cidr":"0.0.0.0/0"}'

Delete a firewall rule

DELETE /orders/{order}/firewall-rules/{firewallRule}

Removes a saved rule.

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

Path parameters

Field	Type
`order`	integer
`firewallRule`	integer

Responses

204 Done, no content returned
403 Not allowed, the resource is not yours
404 Not found

Example

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

List static IPs of a VM

GET /orders/{order}/static-ips

Returns the addresses recorded for the VM.

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

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns: data (list of StaticIp).
403 Not allowed, the resource is not yours

Example

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

Reserve a static IP

POST /orders/{order}/static-ips

Records an address for the VM. With is_reserved it is kept if the VM is deleted and can be attached to another VM.

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

Path parameters

Field	Type
`order`	integer

Request body (application/json)

Field	Type	Required
`ip_address`	string	Yes
`label`	string	No
`is_reserved`	boolean	No

Responses

201 Created. Returns StaticIp.
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/static-ips \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ip_address":"203.0.113.10"}'

Release a static IP

DELETE /orders/{order}/static-ips/{staticIp}

Removes the address record.

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

Path parameters

Field	Type
`order`	integer
`staticIp`	integer

Responses

204 Done, no content returned
403 Not allowed, the resource is not yours
404 Not found

Example

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

List snapshots of a VM

GET /orders/{order}/snapshots

Returns the VM's snapshots and their status.

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

Path parameters

Field	Type
`order`	integer

Responses

200 OK. Returns: data (list of Snapshot).
403 Not allowed, the resource is not yours

Example

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

Create a snapshot

POST /orders/{order}/snapshots

Asks the provider to snapshot the VM's disk. It starts as pending and becomes completed, with its real size, when the provider finishes; only completed snapshots can be restored, copied or used to start a VM.

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
`name`	string	Yes
`size_gb`	integer	No

Responses

201 Created. Returns Snapshot.
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/snapshots \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-name"}'

Delete a snapshot

DELETE /orders/{order}/snapshots/{snapshot}

Deletes the snapshot. It does not touch the VM.

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

Path parameters

Field	Type
`order`	integer
`snapshot`	integer

Responses

204 Done, no content returned
403 Not allowed, the resource is not yours
404 Not found

Example

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

Copy a snapshot

POST /orders/{order}/snapshots/{snapshot}/copy

Copies a completed snapshot to the same VM or to another of your VMs on the same provider and region. OVHcloud does not support provider-side copies.

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

Path parameters

Field	Type
`order`	integer
`snapshot`	integer

Request body (application/json)

Field	Type	Required	Values
`name`	string	Yes
`target_order_id`	integer	No

Responses

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

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/snapshots/SNAPSHOT_ID/copy \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-name"}'

Get a VM's reverse DNS

GET /orders/{order}/reverse-dns

Returns the PTR name set for the VM's public IPv4, or null.

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

Path parameters

Field	Type
`order`	integer

Responses

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

Example

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

Set a VM's reverse DNS

PUT /orders/{order}/reverse-dns

Sets, or with hostname: null removes, the PTR name of the VM's public IPv4. The hostname's own A record must already point to the IP, otherwise 422 with error: forward_record_missing.

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
`hostname`	string	Yes

Responses

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

Example

curl -X PUT https://veneshcloud.ir/api/orders/ORDER_ID/reverse-dns \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"my-vm"}'

Get snapshot pricing

GET /orders/{order}/snapshots/pricing

Returns the price per GB and the most a snapshot of this VM can cost (its disk size), and whether your wallet covers it. The real charge is taken when the snapshot completes, by its real size.

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

Path parameters

Field	Type
`order`	integer

Responses

200 OK

Example

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

Renew a snapshot

POST /orders/{order}/snapshots/{snapshot}/renew

Pays the next period of a snapshot now. Allowed when it is overdue or within 7 days of its renewal date. Lifts the restore and copy block on an overdue snapshot.

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

Path parameters

Field	Type
`order`	integer
`snapshot`	integer

Responses

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

Example

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

List all static IPs

GET /account/static-ips

Returns static IPs across all your VMs, each with its VM hostname.

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

Responses

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

Example

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

Attach a reserved IP to another VM

POST /account/static-ips/{staticIp}/reassign

Moves a reserved address record to another of your VMs.

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

Path parameters

Field	Type
`staticIp`	integer

Request body (application/json)

Field	Type	Required	Values
`order_id`	integer	Yes

Responses

200 OK. Returns StaticIp.
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/account/static-ips/IP_ID/reassign \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_id":1}'

List all firewall rules

GET /account/firewall-rules

Returns firewall rules across all your VMs.

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

Responses

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

Example

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

List all snapshots

GET /account/snapshots

Returns snapshots across all your VMs.

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

Responses

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

Example

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

Objects

Field lists for the objects returned above.

FirewallRule

Field	Type	Values
`id`	integer
`order_id`	integer
`hostname`	string
`direction`	string	`in`, `out`
`protocol`	string	`tcp`, `udp`, `icmp`
`port_range`	string
`source_cidr`	string
`description`	string
`created_at`	string

Snapshot

Field	Type	Values
`id`	integer
`order_id`	integer
`hostname`	string
`name`	string
`size_gb`	integer
`status`	string	`pending`, `completed`, `failed`
`external_id`	string
`copied_from_snapshot_id`	integer
`failure_reason`	string
`billing`	`SnapshotBilling`
`created_at`	string

SnapshotBilling

Field	Type	Values
`state`	string	`active`, `overdue`
`price_usd`	string
`price_rial`	integer
`period_days`	integer
`paid_until`	string
`next_renewal_at`	string
`delete_at`	string

StaticIp

Field	Type	Values
`id`	integer
`order_id`	integer
`hostname`	string
`ip_address`	string
`label`	string
`is_reserved`	boolean
`assigned_at`	string
`created_at`	string