Skip to main content

Arianet Cloud API Endpoints

Complete API reference for the Arianet Cloud Platform. All authenticated endpoints require an API token.

Quick Start​

1. Get an API Token​

# Contact support or use the dashboard to generate a token
# Place it in your request header as: Authorization: Bearer YOUR_TOKEN

2. Make Your First Request​

curl -X GET "https://api.arianet.io/api/v1/balance" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. List Your Servers​

curl -X GET "https://api.arianet.io/api/v1/servers" \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication Overview​

Arianet API uses Bearer token authentication. Include your API token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Getting Your Token​

  1. Log in to the Arianet Dashboard
  2. Navigate to Settings → API Tokens
  3. Click Generate New Token
  4. Copy and store the token securely (it's shown once!)

Token Security Best Practices​

  • Never expose tokens in client-side code or version control
  • Use environment variables to store tokens in production
  • Rotate tokens regularly to minimize exposure
  • Create separate tokens for different applications or environments
  • Use IP allowlists to restrict token usage by source IP

Rate Limiting​

Arianet API implements intelligent rate limiting to ensure fair usage:

CategoryLimitWindowNote
Public100 requests15 minutesRegions, plans, OS templates (no auth required)
Read Operations100 requests15 minutesGET endpoints for servers, balance, tokens
Write Operations1000 requests15 minutesPOST, PUT, DELETE for resource creation/modification

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1693478400

When rate limited, you'll receive a 429 Too Many Requests response. Implement exponential backoff for retries.

Error Handling​

All errors follow a consistent JSON format:

{
  "error": "INVALID_REQUEST",
  "message": "Detailed error message",
  "status": 400
}

Common Status Codes​

CodeMeaningAction
200SuccessRequest completed successfully
201CreatedResource created successfully
400Bad RequestCheck request format and parameters
401UnauthorizedVerify API token is valid and not expired
403ForbiddenYou don't have permission for this resource
404Not FoundResource doesn't exist or was deleted
429Too Many RequestsRate limit exceeded, wait before retrying
500Server ErrorTry again later, contact support if persists

Common Response Objects​

These examples show the object shapes used inside endpoint responses. The authoritative source is the endpoint example itself.

User​

Returned by GET /api/v1/auth/me inside data.

{
  "id": 12345,
  "email": "user@example.com",
  "mobile": "+1234567890",
  "status": "active",
  "verified": true
}

Service (Server)​

Returned by server list and detail endpoints inside data.

{
  "id": 98765,
  "hostname": "web-server-1",
  "status": "active",
  "instance_status": "running",
  "datacenter": {
    "id": 1,
    "name": "us-east-1",
    "display_name": "US East (N. Virginia)"
  },
  "plan": {
    "id": 1,
    "name": "Standard 2GB"
  },
  "os": {
    "id": 5,
    "name": "Ubuntu 22.04 LTS"
  },
  "ip_addresses": [
    {
      "ip": "192.168.1.10",
      "type": "primary"
    }
  ],
  "protected": false,
  "cycle": "monthly",
  "created_at": "2024-01-15T10:30:00Z"
}

Wallet (Balance)​

Returned by GET /api/v1/balance inside data.

{
  "id": 1,
  "balance": 150.5,
  "primary": true,
  "status": "active",
  "currency": {
    "id": 1,
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$"
  }
}

Transaction​

Returned by GET /api/v1/balance/transactions inside data.transactions[].

{
  "id": 5001,
  "type": "debit",
  "amount": 29.99,
  "description": "Monthly server charge - web-server-1",
  "created_at": "2024-01-20T08:15:00Z"
}

Plan Group​

Returned by GET /api/v1/plans/datacenter/{datacenter_id} inside data.groups[].

{
  "id": 10,
  "name": "Standard Plans",
  "plans": [
    {
      "id": 1,
      "name": "Standard 2GB",
      "display_name": "Standard 2GB",
      "recommended": false,
      "cycle": "monthly",
      "cpu": {
        "size": 1,
        "unit": "vCPU"
      },
      "ram": {
        "size": 2,
        "unit": "GB"
      },
      "storage": {
        "size": 20,
        "unit": "GB"
      },
      "prices": [
        {
          "code": "USD",
          "currency": "$",
          "hourly": "0.05",
          "monthly": "29.99",
          "yearly": "299.90"
        }
      ]
    }
  ]
}

Plan​

Returned by GET /api/v1/plans/{id} inside data.

{
  "id": 1,
  "name": "Standard 2GB",
  "display_name": "Standard 2GB",
  "recommended": false,
  "cycle": "monthly",
  "cpu": {
    "size": 1,
    "unit": "vCPU"
  },
  "ram": {
    "size": 2,
    "unit": "GB"
  },
  "storage": {
    "size": 20,
    "unit": "GB"
  },
  "prices": [
    {
      "code": "USD",
      "currency": "$",
      "hourly": "0.05",
      "monthly": "29.99",
      "yearly": "299.90"
    }
  ]
}

Region (Datacenter)​

Returned by GET /api/v1/regions inside data.regions[].

{
  "id": 1,
  "name": "us-east-1",
  "display_name": "US East (N. Virginia)",
  "country": "US"
}

OS Template​

Returned by GET /api/v1/os/datacenter/{datacenter_id} inside data.operating_systems[].

{
  "id": 5,
  "name": "Ubuntu 22.04 LTS",
  "category": "Linux"
}

API Token​

Returned by GET /api/v1/auth/tokens inside data.tokens[].

{
  "id": 1,
  "name": "CLI Token",
  "prefix": "arr_abc123...",
  "last_used": "2024-01-20T15:30:00Z",
  "expires": null,
  "created_at": "2024-01-15T10:00:00Z"
}

SSH Key​

Returned by SSH key endpoints inside data.

{
  "id": 1001,
  "name": "My Laptop",
  "fingerprint": "SHA256:AbCd+EfG...",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
  "created_at": "2024-01-10T14:22:00Z"
}

Firewall​

Returned by firewall endpoints inside data.

{
  "id": 2001,
  "name": "Web Server Firewall",
  "protected": false,
  "rules": [
    {
      "protocol": "tcp",
      "port": 80,
      "direction": "in",
      "cidr": "0.0.0.0/0"
    }
  ],
  "created_at": "2024-01-12T09:45:00Z"
}

Authentication​

Get Current User​

GET /api/v1/auth/me
Authorization: Bearer {token}

Retrieve information about the currently authenticated user.

Response:

{
  "data": {
    "id": 12345,
    "email": "user@example.com",
    "mobile": "+1234567890",
    "status": "active",
    "verified": true
  }
}

List API Tokens​

GET /api/v1/auth/tokens
Authorization: Bearer {token}

List all API tokens for the authenticated user.

Response:

{
  "data": {
    "tokens": [
      {
        "id": 1,
        "name": "CLI Token",
        "prefix": "arr_abc123...",
        "last_used": "2024-01-20T15:30:00Z",
        "expires": null,
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

Revoke Token​

DELETE /api/v1/auth/tokens/{id}
Authorization: Bearer {token}

Revoke a specific API token by ID.

Parameters:

  • id (path, required): Token ID

Response:

{
  "data": {
    "message": "Token revoked successfully"
  }
}

Logout​

DELETE /api/v1/auth/logout
Authorization: Bearer {token}

Revoke the current API token used for authentication.

Response:

{
  "data": {
    "message": "Token revoked successfully"
  }
}

Servers (Services)​

List Servers​

GET /api/v1/servers?page=1&limit=15&status=active
Authorization: Bearer {token}

List all servers for the authenticated user.

Query Parameters:

  • page (integer, default: 1): Page number for pagination
  • limit (integer, default: 15, max: 100): Results per page
  • status (string, optional): Filter by status (active, suspended, creating, failed, terminated, pending)

Response:

{
  "data": [
    {
      "id": 98765,
      "hostname": "web-server-1",
      "status": "active",
      "instance_status": "running",
      "datacenter": {
        "id": 1,
        "name": "us-east-1",
        "display_name": "US East (N. Virginia)"
      },
      "plan": {
        "id": 1,
        "name": "Standard 2GB"
      },
      "os": {
        "id": 5,
        "name": "Ubuntu 22.04 LTS"
      },
      "ip_addresses": [
        {
          "ip": "192.168.1.10",
          "type": "primary"
        }
      ],
      "protected": false,
      "cycle": "monthly",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3
  }
}

Get Server Details​

GET /api/v1/servers/{id}
Authorization: Bearer {token}

Get detailed information about a specific server.

Parameters:

  • id (path, required): Server ID

Response:

{
  "data": {
    "id": 98765,
    "hostname": "web-server-1",
    "status": "active",
    "instance_status": "running",
    "datacenter": {
      "id": 1,
      "name": "us-east-1",
      "display_name": "US East (N. Virginia)"
    },
    "plan": {
      "id": 1,
      "name": "Standard 2GB"
    },
    "os": {
      "id": 5,
      "name": "Ubuntu 22.04 LTS"
    },
    "ip_addresses": [
      {
        "ip": "192.168.1.10",
        "type": "primary"
      },
      {
        "ip": "192.168.1.11",
        "type": "secondary"
      }
    ],
    "protected": false,
    "cycle": "monthly",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Get Server Status​

GET /api/v1/servers/{id}/status
Authorization: Bearer {token}

Quick status check for a server without full details.

Parameters:

  • id (path, required): Server ID

Response:

{
  "data": {
    "id": 98765,
    "status": "active",
    "instance_status": "running"
  }
}

Create Server​

POST /api/v1/servers
Authorization: Bearer {token}
Content-Type: application/json

Create a new cloud server.

Request Body:

{
  "datacenter_id": 1,
  "plan_id": 1,
  "os_id": 5,
  "hostname": "web-server-1",
  "project_id": null
}

Parameters:

  • datacenter_id (integer, required): Datacenter/Region ID
  • plan_id (integer, required): Server plan ID
  • os_id (integer, required): OS template ID
  • hostname (string, optional): Server hostname
  • project_id (integer, optional): Project ID for organization

Response: (201 Created)

{
  "data": {
    "id": 99999,
    "hostname": "web-server-1",
    "status": "creating",
    "instance_status": "initializing",
    "datacenter": {
      "id": 1,
      "name": "us-east-1"
    },
    "plan": {
      "id": 1,
      "name": "Standard 2GB"
    },
    "os": {
      "id": 5,
      "name": "Ubuntu 22.04 LTS"
    },
    "ip_addresses": [],
    "protected": false,
    "cycle": "monthly",
    "created_at": "2024-01-21T10:30:00Z"
  }
}

Restart Server​

POST /api/v1/servers/{id}/restart
Authorization: Bearer {token}

Perform a graceful restart of a running server.

Parameters:

  • id (path, required): Server ID

Response:

{
  "data": {
    "message": "Server restart initiated"
  }
}

Power On Server​

POST /api/v1/servers/{id}/power-on
Authorization: Bearer {token}

Power on a server that is currently powered off.

Parameters:

  • id (path, required): Server ID

Response:

{
  "data": {
    "message": "Server power-on initiated"
  }
}

Power Off Server​

POST /api/v1/servers/{id}/power-off
Authorization: Bearer {token}

Power off a running server.

Parameters:

  • id (path, required): Server ID

Response:

{
  "data": {
    "message": "Server power-off initiated"
  }
}

Rename Server​

POST /api/v1/servers/{id}/rename
Authorization: Bearer {token}
Content-Type: application/json

Change the hostname of a server.

Parameters:

  • id (path, required): Server ID

Request Body:

{
  "hostname": "new-web-server"
}

Response:

{
  "data": {
    "message": "Server rename initiated"
  }
}

Reinstall OS​

POST /api/v1/servers/{id}/reinstall
Authorization: Bearer {token}
Content-Type: application/json

Reinstall the operating system on a server. Warning: All data will be lost.

Parameters:

  • id (path, required): Server ID

Request Body:

{
  "os_id": 6
}

Response:

{
  "data": {
    "message": "OS reinstall initiated"
  }
}

Toggle Protection​

POST /api/v1/servers/{id}/toggle-protection
Authorization: Bearer {token}

Enable or disable deletion protection for a server.

Parameters:

  • id (path, required): Server ID

Response:

{
  "data": {
    "protected": true,
    "message": "Server protection toggled"
  }
}

Delete Server​

DELETE /api/v1/servers/{id}
Authorization: Bearer {token}

Delete a server. Warning: This action is permanent and all data will be lost.

Parameters:

  • id (path, required): Server ID

Response: (204 No Content)

Catalog (Public Endpoints - No Authentication Required)​

List Regions​

GET /api/v1/regions

List all available datacenters/regions.

Response:

{
  "data": {
    "regions": [
      {
        "id": 1,
        "name": "us-east-1",
        "display_name": "US East (N. Virginia)",
        "country": "US"
      },
      {
        "id": 2,
        "name": "eu-west-1",
        "display_name": "EU West (Ireland)",
        "country": "IE"
      },
      {
        "id": 3,
        "name": "ap-southeast-1",
        "display_name": "Asia Pacific (Singapore)",
        "country": "SG"
      }
    ]
  }
}

List Plans by Datacenter​

GET /api/v1/plans/datacenter/{datacenter_id}

List all available server plans for a specific datacenter with pricing.

Parameters:

  • datacenter_id (path, required): Datacenter ID

Response:

{
  "data": {
    "groups": [
      {
        "id": 10,
        "name": "Standard Plans",
        "plans": [
          {
            "id": 1,
            "name": "Standard 2GB",
            "display_name": "Standard 2GB",
            "recommended": false,
            "cycle": "monthly",
            "cpu": {
              "size": 1,
              "unit": "vCPU"
            },
            "ram": {
              "size": 2,
              "unit": "GB"
            },
            "storage": {
              "size": 20,
              "unit": "GB"
            },
            "prices": [
              {
                "code": "USD",
                "currency": "$",
                "hourly": "0.05",
                "monthly": "29.99",
                "yearly": "299.90"
              },
              {
                "code": "EUR",
                "currency": "€",
                "hourly": "0.045",
                "monthly": "27.99",
                "yearly": "279.90"
              }
            ]
          }
        ]
      }
    ]
  }
}

Get Plan Details​

GET /api/v1/plans/{id}

Get detailed information about a specific plan.

Parameters:

  • id (path, required): Plan ID

Response:

{
  "data": {
    "id": 1,
    "name": "Standard 2GB",
    "display_name": "Standard 2GB",
    "recommended": false,
    "cycle": "monthly",
    "cpu": {
      "size": 1,
      "unit": "vCPU"
    },
    "ram": {
      "size": 2,
      "unit": "GB"
    },
    "storage": {
      "size": 20,
      "unit": "GB"
    },
    "prices": [
      {
        "code": "USD",
        "currency": "$",
        "hourly": "0.05",
        "monthly": "29.99",
        "yearly": "299.90"
      }
    ]
  }
}

List Operating Systems by Datacenter​

GET /api/v1/os/datacenter/{datacenter_id}

List all available OS templates for a specific datacenter.

Parameters:

  • datacenter_id (path, required): Datacenter ID

Response:

{
  "data": {
    "operating_systems": [
      {
        "id": 5,
        "name": "Ubuntu 22.04 LTS",
        "category": "Linux"
      },
      {
        "id": 6,
        "name": "Debian 12",
        "category": "Linux"
      },
      {
        "id": 7,
        "name": "CentOS 9",
        "category": "Linux"
      }
    ]
  }
}

SSH Keys​

List SSH Keys​

GET /api/v1/ssh-keys
Authorization: Bearer {token}

List all SSH keys in the authenticated user's account.

Response:

{
  "data": [
    {
      "id": 1001,
      "name": "My Laptop",
      "fingerprint": "SHA256:AbCd+EfG...",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
      "created_at": "2024-01-10T14:22:00Z"
    }
  ]
}

Get SSH Key Details​

GET /api/v1/ssh-keys/{id}
Authorization: Bearer {token}

Get details of a specific SSH key.

Parameters:

  • id (path, required): SSH Key ID

Response:

{
  "data": {
    "id": 1001,
    "name": "My Laptop",
    "fingerprint": "SHA256:AbCd+EfG...",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
    "created_at": "2024-01-10T14:22:00Z"
  }
}

Create SSH Key​

POST /api/v1/ssh-keys
Authorization: Bearer {token}
Content-Type: application/json

Add a new SSH public key to the account.

Request Body:

{
  "name": "Production Key",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC..."
}

Response: (201 Created)

{
  "data": {
    "id": 1004,
    "name": "Production Key",
    "fingerprint": "SHA256:AbCd+EfG...",
    "created_at": "2024-01-20T14:45:00Z"
  }
}

Update SSH Key​

PUT /api/v1/ssh-keys/{id}
Authorization: Bearer {token}
Content-Type: application/json

Update an SSH key's metadata.

Parameters:

  • id (path, required): SSH Key ID

Request Body:

{
  "name": "Updated Key Name"
}

Response:

{
  "data": {
    "id": 1001,
    "name": "Updated Key Name",
    "fingerprint": "SHA256:AbCd+EfG...",
    "created_at": "2024-01-10T14:22:00Z"
  }
}

Delete SSH Key​

DELETE /api/v1/ssh-keys/{id}
Authorization: Bearer {token}

Remove an SSH key from the account.

Parameters:

  • id (path, required): SSH Key ID

Response: (204 No Content)

Firewalls​

List Firewalls​

GET /api/v1/firewalls
Authorization: Bearer {token}

List all firewall groups in the account.

Response:

{
  "data": [
    {
      "id": 2001,
      "name": "Web Server Firewall",
      "protected": false,
      "rules": [
        {
          "protocol": "tcp",
          "port": 80,
          "direction": "in",
          "cidr": "0.0.0.0/0"
        },
        {
          "protocol": "tcp",
          "port": 443,
          "direction": "in",
          "cidr": "0.0.0.0/0"
        }
      ],
      "created_at": "2024-01-12T09:45:00Z"
    }
  ]
}

Get Firewall Details​

GET /api/v1/firewalls/{id}
Authorization: Bearer {token}

Get details of a specific firewall including all rules.

Parameters:

  • id (path, required): Firewall ID

Response:

{
  "data": {
    "id": 2001,
    "name": "Web Server Firewall",
    "protected": false,
    "rules": [
      {
        "index": 0,
        "protocol": "tcp",
        "port": 80,
        "direction": "in",
        "cidr": "0.0.0.0/0"
      },
      {
        "index": 1,
        "protocol": "tcp",
        "port": 443,
        "direction": "in",
        "cidr": "0.0.0.0/0"
      },
      {
        "index": 2,
        "protocol": "tcp",
        "port": 22,
        "direction": "in",
        "cidr": "203.0.113.0/24"
      }
    ],
    "created_at": "2024-01-12T09:45:00Z"
  }
}

Create Firewall​

POST /api/v1/firewalls
Authorization: Bearer {token}
Content-Type: application/json

Create a new firewall group.

Request Body:

{
  "name": "My Firewall"
}

Response: (201 Created)

{
  "data": {
    "id": 2004,
    "name": "My Firewall",
    "protected": false,
    "rules": [],
    "created_at": "2024-01-20T14:45:00Z"
  }
}

Add Firewall Rule​

POST /api/v1/firewalls/{id}/rules
Authorization: Bearer {token}
Content-Type: application/json

Add a new rule to a firewall.

Parameters:

  • id (path, required): Firewall ID

Request Body:

{
  "protocol": "tcp",
  "port": 80,
  "direction": "in",
  "cidr": "0.0.0.0/0"
}

Response:

{
  "data": {
    "message": "Rule added successfully"
  }
}

Delete Firewall Rule​

DELETE /api/v1/firewalls/{id}/rules/{rule_index}
Authorization: Bearer {token}

Remove a specific rule from a firewall.

Parameters:

  • id (path, required): Firewall ID
  • rule_index (path, required): Rule index (0-based)

Response: (204 No Content)

Delete Firewall​

DELETE /api/v1/firewalls/{id}
Authorization: Bearer {token}

Delete an entire firewall group including all rules.

Parameters:

  • id (path, required): Firewall ID

Response: (204 No Content)

Account & Billing​

Get Account Balance​

GET /api/v1/balance
Authorization: Bearer {token}

Retrieve current account balance and credit information.

Response:

{
  "data": {
    "balance": 150.50,
    "currency": "USD",
    "status": "active",
    "used_this_month": 45.25,
    "remaining": 105.25
  }
}

Get Transaction History​

GET /api/v1/balance/transactions?page=1&limit=50
Authorization: Bearer {token}

View account transaction history.

Query Parameters:

  • page (integer, default: 1): Page number
  • limit (integer, default: 50): Results per page

Response:

{
  "data": [
    {
      "id": 5001,
      "type": "debit",
      "amount": 29.99,
      "description": "Monthly server charge - web-server-1",
      "date": "2024-01-20T00:00:00Z"
    },
    {
      "id": 5002,
      "type": "credit",
      "amount": 50.00,
      "description": "Account credit applied",
      "date": "2024-01-18T12:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 128,
    "last_page": 3
  }
}

Error Handling​

All API responses follow a consistent error format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "additional_context"
    }
  }
}

Common Error Codes​

CodeHTTP StatusDescription
INVALID_ID400Invalid resource ID format
VALIDATION_ERROR400Request validation failed
UNAUTHORIZED401Missing or invalid authentication token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
CONFLICT409Resource conflict (e.g., duplicate)
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_SERVER_ERROR500Server error

Rate Limiting​

Public endpoints are rate limited by IP: 100 requests/minute Authenticated endpoints: 1000 requests/minute Write operations: 100 requests/minute

Rate limit information is returned in response headers:

  • X-RateLimit-Limit: Maximum requests in window
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets