Venesh Cloud
ENFA

API: Firewalls, floating IPs and live VM data

Security groups and their rules, floating IPs, a VM's live addresses and what the provider allows in a region.

Everything here is applied at the cloud provider. Firewall calls answer with the real result; when the provider refuses, you get 422 with error (for example QUOTA_EXCEEDED) and a readable message. Floating-IP changes answer 202; poll GET /floating-ips until the status settles. Check GET /orders/{order}/capabilities first to see whether the provider allows a feature in that region.

Get live VM details

GET /orders/{order}/instance

Asks the provider for the VM's current state and every address: its own public IPv4 and IPv6, private addresses and floating IPs.

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

Path parameters

Field Type
order integer

Responses

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

Example

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

Get a floating IP's reverse DNS

GET /floating-ips/{floatingIp}/reverse-dns

Returns the PTR name set for the floating IP, or null.

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

Path parameters

Field Type
floatingIp 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

Example

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

Set a floating IP's reverse DNS

PUT /floating-ips/{floatingIp}/reverse-dns

Same rules as for a VM, including forward_record_missing.

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

Path parameters

Field Type
floatingIp 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

Example

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

Get VM capabilities

GET /orders/{order}/capabilities

Says which features the provider allows for this VM's region right now. An unavailable feature names the blocking quota and gives a readable message.

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

Path parameters

Field Type
order integer

Responses

  • 200 OK. Returns: data (Capabilities).

Example

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

Get region capabilities

GET /provider-capabilities

The same as the VM capabilities, for a provider and region.

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

Query parameters

Field Type Values
provider string
region string

Responses

  • 200 OK. Returns: data (Capabilities).

Example

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

List a VM's firewalls

GET /orders/{order}/security-groups

Returns the firewalls attached to the VM, with their rules.

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

Path parameters

Field Type
order integer

Responses

  • 200 OK. Returns: data (list of SecurityGroup).

Example

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

List firewalls

GET /security-groups

Returns your firewalls with their rules and attached VMs.

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

Responses

  • 200 OK. Returns: data (list of SecurityGroup).

Example

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

Create a firewall

POST /security-groups

Creates a security group at the provider in the given region, with the given rules.

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

Request body (application/json)

Field Type Required Values
provider string Yes
region string Yes
name string Yes
description string No
rules list of SecurityGroupRule No

Responses

  • 201 Created. Returns: data (SecurityGroup).
  • 422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/security-groups \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"provider":"aws","region":"REGION","name":"my-name"}'

Rename a firewall

PATCH /security-groups/{securityGroup}

Changes a firewall's name or description.

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

Path parameters

Field Type
securityGroup integer

Request body (application/json)

Field Type Required Values
name string No
description string No

Responses

  • 200 OK

Example

curl -X PATCH https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Delete a firewall

DELETE /security-groups/{securityGroup}

Deletes a firewall at the provider. Detach it from every VM first.

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

Path parameters

Field Type
securityGroup integer

Responses

  • 204 Done, no content returned
  • 422 Validation error, or not allowed in the current state

Example

curl -X DELETE https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Add a firewall rule

POST /security-groups/{securityGroup}/rules

Adds one rule: direction, protocol, optional ports and a CIDR range.

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

Path parameters

Field Type
securityGroup integer

Request body (application/json)

Field Type Required Values
id integer No
direction string Yes ingress, egress
protocol string Yes tcp, udp, icmp, any
port_min integer No
port_max integer No
remote_cidr string Yes
description string No

Responses

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

Example

curl -X POST https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/rules \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"direction":"ingress","protocol":"tcp","remote_cidr":"string"}'

Replace firewall rules

PUT /security-groups/{securityGroup}/rules

Replaces all rules of a firewall with the list you send.

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

Path parameters

Field Type
securityGroup integer

Request body (application/json)

Field Type Required Values
rules list of SecurityGroupRule Yes

Responses

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

Example

curl -X PUT https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/rules \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"rules":[]}'

Remove a firewall rule

DELETE /security-groups/{securityGroup}/rules/{rule}

Removes one rule from a firewall.

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

Path parameters

Field Type
securityGroup integer
rule integer

Responses

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

Example

curl -X DELETE https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/rules/RULE_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Attach a firewall

POST /security-groups/{securityGroup}/attach

Attaches the firewall to one of your VMs in the same region. From then on only traffic its rules allow reaches the VM.

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

Path parameters

Field Type
securityGroup integer

Request body (application/json)

Field Type Required Values
order_id integer Yes

Responses

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

Example

curl -X POST https://veneshcloud.ir/api/security-groups/SECURITY_GROUP_ID/attach \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_id":1}'

Detach a firewall

DELETE /security-groups/{securityGroup}/orders/{order}

Detaches the firewall from a VM. With no firewall left, the VM goes back to the provider's default open group.

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

Path parameters

Field Type
securityGroup integer
order integer

Responses

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

Example

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

List a VM's floating IPs

GET /orders/{order}/floating-ips

Returns the floating IPs attached to, or being attached to, 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 FloatingIp).

Example

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

Get floating IP pricing

GET /floating-ips/pricing

Returns the price of one floating-IP billing period in USD-equivalent and in Rial at today's rate, plus your wallet balance and whether it covers one period. Show it before a reservation.

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

Responses

  • 200 OK. Returns: data (FloatingIpPricing).

Example

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

Renew a floating IP

POST /floating-ips/{floatingIp}/renew

Pays the next period from your wallet now. Allowed when the IP is overdue or close to its renewal date. Answers 422 with a readable message if the balance is too low.

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

Responses

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

Example

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

List floating IPs

GET /floating-ips

Returns your floating IPs and their status.

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

Responses

  • 200 OK. Returns: data (list of FloatingIp).

Example

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

Get a floating IP

POST /floating-ips

Asks the provider for a new address. Send order_id to reserve it for that VM and attach it, or provider and region. One period is charged to your wallet first (refunded if the provider fails); 422 if the balance is too low. Answers 202.

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

Request body (application/json)

Field Type Required Values
order_id integer No
provider string No
region string No
label string No

Responses

  • 202 Accepted, work continues in the background. Returns: data (FloatingIp).
  • 422 Validation error, or not allowed in the current state

Example

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

Label a floating IP

PATCH /floating-ips/{floatingIp}

Changes a floating IP's label.

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

Path parameters

Field Type
floatingIp integer

Request body (application/json)

Field Type Required Values
label string No

Responses

  • 200 OK

Example

curl -X PATCH https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Release a floating IP

DELETE /floating-ips/{floatingIp}

Gives the address back to the provider. Answers 202; the IP disappears from the list once released.

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

Path parameters

Field Type
floatingIp integer

Responses

  • 202 Accepted, work continues in the background
  • 204 Done, no content returned

Example

curl -X DELETE https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Attach a floating IP

POST /floating-ips/{floatingIp}/attach

Attaches an available floating IP to one of your VMs in the same region. Answers 202.

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

Path parameters

Field Type
floatingIp integer

Request body (application/json)

Field Type Required Values
order_id integer Yes

Responses

  • 202 Accepted, work continues in the background
  • 422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID/attach \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_id":1}'

Move a floating IP

POST /floating-ips/{floatingIp}/move

Moves an attached floating IP to another of your VMs in the same region: it is detached, then attached to the VM in order_id. Answers 202; poll GET /floating-ips. Billing is unchanged.

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

Path parameters

Field Type
floatingIp integer

Request body (application/json)

Field Type Required Values
order_id integer Yes

Responses

  • 202 Accepted, work continues in the background
  • 404 Not found
  • 422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID/move \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"order_id":1}'

Detach a floating IP

POST /floating-ips/{floatingIp}/detach

Detaches the address from its VM. It stays yours. Answers 202.

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

Path parameters

Field Type
floatingIp integer

Responses

  • 202 Accepted, work continues in the background

Example

curl -X POST https://veneshcloud.ir/api/floating-ips/FLOATING_IP_ID/detach \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Objects

Field lists for the objects returned above.

Capabilities

Field Type Values
provider string
region string
features object

FloatingIp

Field Type Values
id integer
provider string
region string
label string
ip_address string
status string allocating, available, attaching, attached, detaching, releasing, failed
order_id integer
hostname string
pending_order_id integer
failure_reason string
billing object
created_at string

FloatingIpPricing

Field Type Values
usd_equivalent_price string
period_days integer
rial integer
fx_rate_id integer
as_of string
wallet_balance_usd string
wallet_balance_rial integer
sufficient_balance boolean
auto_renew boolean

LiveInstance

Field Type Values
status string
provider_status string
launched_at string
outgoing_traffic_bytes integer
plan string
ipv4_address string
ipv6_address string
addresses list of object

SecurityGroup

Field Type Values
id integer
provider string
region string
name string
description string
external_id string
rules list of SecurityGroupRule
orders list of object
created_at string

SecurityGroupRule

Field Type Values
id integer
direction string ingress, egress
protocol string tcp, udp, icmp, any
port_min integer
port_max integer
remote_cidr string
description string