Arianet API Reference

Welcome to the Arianet API documentation. This guide covers all available endpoints, request/response formats, authentication, rate limiting, and best practices for integrating with the Arianet cloud infrastructure management platform.

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

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Getting Your Token

Log in to the Arianet Dashboard
Navigate to Settings → API Tokens
Click Generate New Token
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:

Category	Limit	Window	Note
Public	100 requests	15 minutes	Regions, plans, OS templates (no auth required)
Read Operations	100 requests	15 minutes	GET endpoints for servers, balance, tokens
Write Operations	1000 requests	15 minutes	POST, 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

Code	Meaning	Action
200	Success	Request completed successfully
201	Created	Resource created successfully
400	Bad Request	Check request format and parameters
401	Unauthorized	Verify API token is valid and not expired
403	Forbidden	You don't have permission for this resource
404	Not Found	Resource doesn't exist or was deleted
429	Too Many Requests	Rate limit exceeded, wait before retrying
500	Server Error	Try again later, contact support if persists

Data Models

User

The authenticated user's profile information.

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

Service (Server)

A virtual server instance managed in Arianet infrastructure.

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

Wallet (Balance)

Account balance and financial information.

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

Transaction

Financial transaction record.

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

Plan

Server plan with specifications and pricing.

{
  "id": 1,
  "name": "Standard 2GB",
  "recommended": false,
  "cycle": "monthly",
  "specs": {
    "cpu": "1 vCPU",
    "memory": "2 GB",
    "storage": "20 GB SSD"
  },
  "prices": [
    {
      "code": "usd",
      "currency": "USD",
      "hourly": 0.05,
      "monthly": 29.99,
      "yearly": 299.90
    }
  ],
  "datacenter": {
    "id": 1,
    "name": "us-east-1",
    "display_name": "US East (N. Virginia)",
    "country": "US"
  }
}

Region (DataCenter)

Server location and infrastructure details.

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

OS Template

Operating system image for server installation.

{
  "id": 5,
  "name": "Ubuntu 22.04 LTS",
  "region_id": 1
}

API Token

User API token information.

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

SSH Key

Public SSH key for server access.

{
  "id": 1001,
  "name": "My Laptop Key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
  "protected": false,
  "created_at": "2024-01-10T14:22:00Z"
}

Firewall

Firewall group with rules.

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

API Endpoints

Authentication

Get Current User

GET /auth/me

Retrieve authenticated user profile information.

Response (200 OK):

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

List API Tokens

GET /auth/tokens

Retrieve all API tokens associated with the authenticated user.

Response (200 OK):

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

Logout / Revoke Current Token

DELETE /auth/logout

Revokes the current API token used for authentication.

Response (200 OK):

{
  "message": "Token revoked successfully"
}

Revoke Specific Token

DELETE /auth/tokens/{id}

Revoke an API token by ID.

Parameters:

id (path, required): Token ID

Response (200 OK):

{
  "message": "Token revoked successfully"
}

Servers

List Servers

GET /servers?page=1&limit=15&status=active

List all servers owned by the authenticated user.

Parameters:

page (query, optional): Page number for pagination (default: 1)
limit (query, optional): Results per page (default: 15, max: 100)
status (query, optional): Filter by status (active, suspended, creating, failed, terminated, pending, request_creating, request_suspend, request_unsuspend, request_activate)

Response (200 OK):

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

Get Server Details

GET /servers/{id}

Retrieve detailed information about a specific server.

Parameters:

id (path, required): Server ID

Response (200 OK):

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

Get Server Status

GET /servers/{id}/status

Quick endpoint to check the current status of a server.

Parameters:

id (path, required): Server ID

Response (200 OK):

{
  "status": "active",
  "instance_status": "running"
}

Create New Server

POST /servers

Create a new server instance in the specified region.

Request Body:

{
  "plan_id": 1,
  "datacenter_id": 1,
  "os_id": 5,
  "hostname": "my-new-server",
  "project_id": 10
}

Parameters:

plan_id (required): ID of the server plan
datacenter_id (required): ID of the datacenter/region
os_id (required): ID of the OS template
hostname (optional): Server hostname
project_id (optional): Project ID for organization

Response (201 Created):

{
  "id": 99999,
  "status": "creating",
  "instance_status": null,
  "hostname": "my-new-server",
  "ip_addresses": [],
  "protected": false,
  "cycle": null,
  "plan": {
    "id": 1,
    "name": "Standard 2GB"
  },
  "datacenter": {
    "id": 1,
    "name": "us-east-1",
    "display_name": "US East (N. Virginia)",
    "country": "US"
  },
  "os": {
    "id": 5,
    "name": "Ubuntu 22.04 LTS"
  },
  "created_at": "2024-01-21T12:00:00Z"
}

Delete Server

DELETE /servers/{id}

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

Parameters:

id (path, required): Server ID

Response (200 OK):

{
  "message": "Server deleted successfully"
}

Restart Server

POST /servers/{id}/restart

Perform a graceful restart of the server.

Parameters:

id (path, required): Server ID

Response (200 OK):

{
  "message": "Restart initiated"
}

Power On Server

POST /servers/{id}/power-on

Power on a server that is currently powered off.

Parameters:

id (path, required): Server ID

Response (200 OK):

{
  "message": "Power on initiated"
}

Power Off Server

POST /servers/{id}/power-off

Power off a running server.

Parameters:

id (path, required): Server ID

Response (200 OK):

{
  "message": "Power off initiated"
}

Rename Server

POST /servers/{id}/rename

Change the hostname of a server.

Parameters:

id (path, required): Server ID

Request Body:

{
  "hostname": "new-hostname"
}

Response (200 OK):

{
  "id": 98765,
  "hostname": "new-hostname"
}

Reinstall OS

POST /servers/{id}/reinstall

Reinstall the operating system on a server.

Parameters:

id (path, required): Server ID

Request Body:

{
  "os_id": 6
}

Response (200 OK):

{
  "message": "OS reinstall initiated"
}

Toggle Protection

POST /servers/{id}/toggle-protection

Enable or disable deletion protection for a server.

Parameters:

id (path, required): Server ID

Response (200 OK):

{
  "protected": true
}

Balance & Billing

Get Balance

GET /balance

Retrieve account balance and wallet information.

Response (200 OK):

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

Get Transactions

GET /balance/transactions?page=1&limit=50

Retrieve billing transactions and charge history.

Parameters:

page (query, optional): Page number for pagination (default: 1)
limit (query, optional): Results per page (default: 50, max: 100)

Response (200 OK):

{
  "data": [
    {
      "id": 5001,
      "type": "debit",
      "amount": 29.99,
      "description": "Monthly server charge - web-server-1",
      "created_at": "2024-01-20T08:15:00Z"
    },
    {
      "id": 5000,
      "type": "credit",
      "amount": 50.00,
      "description": "Account credit applied",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 24,
    "last_page": 1
  }
}

SSH Keys

List SSH Keys

GET /ssh-keys

List all SSH keys associated with your account.

Response (200 OK):

{
  "data": [
    {
      "id": 1001,
      "name": "My Laptop Key",
      "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
      "protected": false,
      "created_at": "2024-01-10T14:22:00Z"
    }
  ]
}

Get SSH Key Details

GET /ssh-keys/{id}

Retrieve a specific SSH key.

Parameters:

id (path, required): SSH Key ID

Response (200 OK):

{
  "id": 1001,
  "name": "My Laptop Key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
  "protected": false,
  "created_at": "2024-01-10T14:22:00Z"
}

Create SSH Key

POST /ssh-keys

Add a new SSH public key to your account.

Request Body:

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

Response (201 Created):

{
  "id": 1002,
  "name": "Production Key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
  "protected": false,
  "created_at": "2024-01-21T09:15:00Z"
}

Update SSH Key

PUT /ssh-keys/{id}

Update an SSH key's metadata.

Parameters:

id (path, required): SSH Key ID

Request Body:

{
  "name": "Updated Key Name"
}

Response (200 OK):

{
  "id": 1001,
  "name": "Updated Key Name",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...",
  "protected": false,
  "created_at": "2024-01-10T14:22:00Z"
}

Delete SSH Key

DELETE /ssh-keys/{id}

Delete an SSH key.

Parameters:

id (path, required): SSH Key ID

Response (200 OK):

{
  "message": "SSH key deleted successfully"
}

Firewalls

List Firewalls

GET /firewalls

List all firewall groups in your account.

Response (200 OK):

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

Get Firewall Details

GET /firewalls/{id}

Retrieve a specific firewall group with all its rules.

Parameters:

id (path, required): Firewall ID

Response (200 OK):

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

Create Firewall

POST /firewalls

Create a new firewall group.

Request Body:

{
  "name": "My Firewall"
}

Response (201 Created):

{
  "id": 2002,
  "name": "My Firewall",
  "protected": false,
  "rules": [],
  "created_at": "2024-01-21T10:30:00Z"
}

Add Firewall Rule

POST /firewalls/{id}/rules

Add a new rule to a firewall group.

Parameters:

id (path, required): Firewall ID

Request Body:

{
  "protocol": "tcp",
  "port": 22,
  "direction": "in",
  "cidr": "203.0.113.0/24"
}

Response (200 OK):

{
  "id": 2001,
  "name": "Web Server Firewall",
  "protected": false,
  "rules": [
    {
      "id": 1,
      "protocol": "tcp",
      "port": 80,
      "direction": "in",
      "cidr": "0.0.0.0/0"
    },
    {
      "id": 2,
      "protocol": "tcp",
      "port": 443,
      "direction": "in",
      "cidr": "0.0.0.0/0"
    },
    {
      "id": 3,
      "protocol": "tcp",
      "port": 22,
      "direction": "in",
      "cidr": "203.0.113.0/24"
    }
  ]
}

Delete Firewall Rule

DELETE /firewalls/{id}/rules/{rule_index}

Remove a specific rule from a firewall group.

Parameters:

id (path, required): Firewall ID
rule_index (path, required): Index of the rule to delete (0-based)

Response (200 OK):

{
  "id": 2001,
  "name": "Web Server Firewall",
  "protected": false,
  "rules": [
    {
      "id": 1,
      "protocol": "tcp",
      "port": 80,
      "direction": "in",
      "cidr": "0.0.0.0/0"
    }
  ]
}

Delete Firewall

DELETE /firewalls/{id}

Delete an entire firewall group including all its rules.

Parameters:

id (path, required): Firewall ID

Response (200 OK):

{
  "message": "Firewall deleted successfully"
}

Regions

List Available Regions

GET /regions

List all available datacenters/regions where you can deploy servers.

Response (200 OK):

{
  "data": [
    {
      "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"
    }
  ]
}

Operating Systems

List Available OS Templates

GET /os

List all available operating system templates.

Response (200 OK):

{
  "data": [
    {
      "id": 5,
      "name": "Ubuntu 22.04 LTS",
      "region_id": 1
    },
    {
      "id": 6,
      "name": "Debian 12",
      "region_id": 1
    }
  ]
}

List OS by Datacenter

GET /os/datacenter/{datacenter_id}

List operating systems available in a specific datacenter.

Parameters:

datacenter_id (path, required): Datacenter/Region ID

Response (200 OK):

{
  "data": [
    {
      "id": 5,
      "name": "Ubuntu 22.04 LTS",
      "region_id": 1
    }
  ]
}

Plans

List Available Plans

GET /plans

List all available server plans with pricing and specifications.

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "Standard 2GB",
      "recommended": false,
      "cycle": "monthly",
      "specs": {
        "cpu": "1 vCPU",
        "memory": "2 GB",
        "storage": "20 GB SSD"
      },
      "prices": [
        {
          "code": "usd",
          "currency": "USD",
          "hourly": 0.05,
          "monthly": 29.99,
          "yearly": 299.90
        }
      ]
    }
  ]
}

Get Plan Details

GET /plans/{id}

Retrieve detailed information about a specific plan.

Parameters:

id (path, required): Plan ID

Response (200 OK):

{
  "id": 1,
  "name": "Standard 2GB",
  "recommended": false,
  "cycle": "monthly",
  "specs": {
    "cpu": "1 vCPU",
    "memory": "2 GB",
    "storage": "20 GB SSD"
  },
  "prices": [
    {
      "code": "usd",
      "currency": "USD",
      "hourly": 0.05,
      "monthly": 29.99,
      "yearly": 299.90
    },
    {
      "code": "eur",
      "currency": "EUR",
      "hourly": 0.045,
      "monthly": 27.99,
      "yearly": 279.90
    }
  ],
  "datacenter": {
    "id": 1,
    "name": "us-east-1",
    "display_name": "US East (N. Virginia)",
    "country": "US"
  }
}

List Plans by Datacenter

GET /plans/datacenter/{datacenter_id}

List server plans available in a specific datacenter/region.

Parameters:

datacenter_id (path, required): Datacenter/Region ID

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "Standard 2GB",
      "recommended": false,
      "cycle": "monthly",
      "specs": {
        "cpu": "1 vCPU",
        "memory": "2 GB",
        "storage": "20 GB SSD"
      },
      "prices": [
        {
          "code": "usd",
          "currency": "USD",
          "hourly": 0.05,
          "monthly": 29.99,
          "yearly": 299.90
        }
      ]
    }
  ]
}

Best Practices

API Usage

Use pagination: Always include page and limit parameters
Implement retries: Use exponential backoff for failed requests (429, 5xx)
Cache responses: Store plan, region, and OS data to reduce API calls
Batch operations: Group related requests when possible
Monitor rate limits: Track X-RateLimit-* headers to avoid hitting limits

Security

Secure token storage: Never hardcode tokens; use environment variables
Use HTTPS: All API calls must use SSL/TLS encryption
Validate SSL certificates: Don't disable certificate validation
Rotate tokens: Replace tokens regularly (monthly or when needed)
IP whitelisting: Use IP allowlists for token restrictions when possible

Error Handling

import requests
import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def requests_retry_session(
    retries=3,
    backoff_factor=0.3,
    status_forcelist=(429, 500, 502, 504),
):
    session = requests.Session()
    retry = Retry(
        total=retries,
        read=retries,
        connect=retries,
        backoff_factor=backoff_factor,
        status_forcelist=status_forcelist,
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount("http://", adapter)
    session.mount("https://", adapter)
    return session

# Usage
response = requests_retry_session().get(
    "https://api.arianet.io/api/v1/servers",
    headers={"Authorization": f"Bearer {token}"}
)

Support & Contact

For API support, feature requests, or issues:

Documentation: https://docs.arianet.io
Email: support@arianet.io
Status Page: https://status.arianet.io
Community: https://community.arianet.io

Last Updated: March 2026
API Version: 1.0
Status: Production

Quick Start​

1. Get an API Token​

2. Make Your First Request​

3. List Your Servers​

Authentication​

Getting Your Token​

Token Security Best Practices​

Rate Limiting​

Error Handling​

Common Status Codes​

Data Models​

User​

Service (Server)​

Wallet (Balance)​

Transaction​

Plan​

Region (DataCenter)​

OS Template​

API Token​

SSH Key​

Firewall​

API Endpoints​

Authentication​

Get Current User​

List API Tokens​

Logout / Revoke Current Token​

Revoke Specific Token​

Servers​

List Servers​

Get Server Details​

Get Server Status​

Create New Server​

Delete Server​

Restart Server​

Power On Server​

Power Off Server​

Rename Server​

Reinstall OS​

Toggle Protection​

Balance & Billing​

Get Balance​

Get Transactions​

SSH Keys​

List SSH Keys​

Get SSH Key Details​

Create SSH Key​

Update SSH Key​

Delete SSH Key​

Firewalls​

List Firewalls​

Get Firewall Details​

Create Firewall​

Add Firewall Rule​

Delete Firewall Rule​

Delete Firewall​

Regions​

List Available Regions​

Operating Systems​

List Available OS Templates​

List OS by Datacenter​

Plans​

List Available Plans​

Get Plan Details​

List Plans by Datacenter​

Best Practices​

API Usage​

Security​

Error Handling​

Support & Contact​

Quick Start

1. Get an API Token

2. Make Your First Request

3. List Your Servers

Authentication

Getting Your Token

Token Security Best Practices

Rate Limiting

Error Handling

Common Status Codes

Data Models

User

Service (Server)

Wallet (Balance)

Transaction

Plan

Region (DataCenter)

OS Template

API Token

SSH Key

Firewall

API Endpoints

Authentication

Get Current User

List API Tokens

Logout / Revoke Current Token

Revoke Specific Token

Servers

List Servers

Get Server Details

Get Server Status

Create New Server

Delete Server

Restart Server

Power On Server

Power Off Server

Rename Server

Reinstall OS

Toggle Protection

Balance & Billing

Get Balance

Get Transactions

SSH Keys

List SSH Keys

Get SSH Key Details

Create SSH Key

Update SSH Key

Delete SSH Key

Firewalls

List Firewalls

Get Firewall Details

Create Firewall

Add Firewall Rule

Delete Firewall Rule

Delete Firewall

Regions

List Available Regions

Operating Systems

List Available OS Templates

List OS by Datacenter

Plans

List Available Plans

Get Plan Details

List Plans by Datacenter

Best Practices

API Usage

Security

Error Handling

Support & Contact