Code Samples #
Copy
curl --request POST \
--url 'https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "ssh-office",
"port": "22",
"ip_address": "203.0.113.10",
"protocol": "tcp",
"traffic": "allow"
}'
const response = await fetch('https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "ssh-office",
"port": "22",
"ip_address": "203.0.113.10",
"protocol": "tcp",
"traffic": "allow"
})
});
const data = await response.json();
console.log(data);
import requests
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json"
}
payload = {
"name": "ssh-office",
"port": "22",
"ip_address": "203.0.113.10",
"protocol": "tcp",
"traffic": "allow"
}
response = requests.post("https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules", headers=headers, json=payload)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_TOKEN',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => '{
"name": "ssh-office",
"port": "22",
"ip_address": "203.0.113.10",
"protocol": "tcp",
"traffic": "allow"
}',
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System.Net.Http;
using System.Text;
var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");
request.Content = new StringContent(@"{
""name"": ""ssh-office"",
""port"": ""22"",
""ip_address"": ""203.0.113.10"",
""protocol"": ""tcp"",
""traffic"": ""allow""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
import java.net.URI;
import java.net.http.*;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules"))
.header("Authorization", "Bearer YOUR_TOKEN")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("""
{
"name": "ssh-office",
"port": "22",
"ip_address": "203.0.113.10",
"protocol": "tcp",
"traffic": "allow"
}
"""))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Response #
Copy
{
"success": true,
"message": "Operation completed successfully.",
"data": {
"uuid": "55ff66aa-77bb-88cc-99dd-00ee11ff2233",
"name": "ssh-admin",
"ip_address": "203.0.113.10",
"port": "22",
"protocol": "tcp",
"traffic": "allow",
"is_active": true,
"description": "Office static IP",
"created_at": "2024-01-15T09:30:00Z",
"updated_at": "2024-01-15T09:30:00Z"
}
}
{
"success": false,
"message": "Unauthenticated.",
"data": null
}
{
"success": false,
"message": "This action is unauthorized. Your token is missing the required scope.",
"data": null
}
{
"success": false,
"message": "Not found.",
"data": null
}
{
"success": false,
"message": "An error occurred.",
"data": null
}
Creates a New firewall rule on the Server. Synchronous — runs InstallFirewall over SSH inline and returns the New row at 201. Idempotent on (name, port, ip_address). Requires the write:servers scope.
Path Parameters #
| Name | Type | Required | Description |
|---|---|---|---|
uuid | string (uuid) | Required | UUID of the Server |
Request Body #
Content type: application/json — required
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | |
port | string | Optional | Empty for all ports, a single port (e.g. `22`), or a range (e.g. `8000:9000`). Port ranges require `protocol` to be `tcp` or `udp` (not `any`). |
ip_address | string | Optional | Comma-separated IPv4 addresses with optional `/CIDR` (e.g. `203.0.113.10,198.51.100.0/24`). Empty matches all IPs. |
protocol | string | Required | Allowed: any, tcp, udp |
traffic | string | Required | Allowed: allow, deny |
Example request
Copy
{
"name": "ssh-office",
"port": "22",
"ip_address": "203.0.113.10",
"protocol": "tcp",
"traffic": "allow"
}
Responses #
201 — Firewall rule created #
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Optional | |
message | string | Optional | |
data | object | Optional | |
data | object | Optional | |
data.uuid | string (uuid) | Optional | |
data.name | string | Optional | |
data.ip_address | string | Optional | |
data.port | string | Optional | Single port or comma/range list as configured (e.g. "22", "80,443", "8000-9000"). |
data.protocol | string | Optional | Allowed: any, tcp, udp |
data.traffic | string | Optional | Allowed: allow, deny |
data.is_active | boolean | Optional | |
data.description | string | Optional | |
data.created_at | string (date-time) | Optional | |
data.updated_at | string (date-time) | Optional |
Example 201 response
Copy
{
"success": true,
"message": "Operation completed successfully.",
"data": {
"uuid": "55ff66aa-77bb-88cc-99dd-00ee11ff2233",
"name": "ssh-admin",
"ip_address": "203.0.113.10",
"port": "22",
"protocol": "tcp",
"traffic": "allow",
"is_active": true,
"description": "Office static IP",
"created_at": "2024-01-15T09:30:00Z",
"updated_at": "2024-01-15T09:30:00Z"
}
}
401 — Missing or invalid authentication token #
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Optional | |
message | string | Optional | |
data | object | Optional |
Example 401 response
Copy
{
"success": false,
"message": "Unauthenticated.",
"data": null
}
403 — Token lacks the required scope #
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Optional | |
message | string | Optional | |
data | object | Optional |
Example 403 response
Copy
{
"success": false,
"message": "This action is unauthorized. Your token is missing the required scope.",
"data": null
}
404 — Resource not found or not accessible to your Team #
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Optional | |
message | string | Optional | |
data | object | Optional |
Example 404 response
Copy
{
"success": false,
"message": "Not found.",
"data": null
}
422 — Validation failure or InstallFirewall SSH error. #
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Optional | |
message | string | Optional | |
data | object | Optional |
Example 422 response
Copy
{
"success": false,
"message": "An error occurred.",
"data": null
}
