Overview

REST API·v1.0

API Reference

Programmatically manage your virtual private servers and Linux containers — start/stop, configure IPs, rebuild, generate passwords, and more.

API Operational

https://api.advps.org

Authentication

Every request must include your API key in the x-api-key header.

Test Mode

x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Safe sandbox — returns mock data

Production Mode

x-api-key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Performs real operations on your VMs

API Modes

The API operates in two modes determined by your API key prefix.

Mode	Prefix	Behaviour
Test	sk_test_*	Returns mock data, no real changes made
Production	sk_live_*	Executes real operations on your infrastructure

Response Format

All responses are JSON. Successful responses use HTTP 200 and wrap data in a consistent envelope.

Success

{
  "status": "success",
  "message": "Operation completed",
  "data": {},
  "timestamp": "2024-01-30T12:00:00.000Z"
}

Error

{
  "status": "error",
  "message": "Error description",
  "errors": null,
  "timestamp": "2024-01-30T12:00:00.000Z"
}

Rate Limiting

Requests are rate-limited per 15-minute window. Exceeded limits return HTTP 429.

Test Mode1,000 req / 15 min

Suitable for development & testing

Production Mode100 req / 15 min

Optimised for production workloads

Services

Service Management

Control and monitor your VPS and Linux container services.

POST/api/v1/services/{serviceId}/start

Start Service

Start a stopped service. Works for both VPS (VM) and Linux (LXC) service types.

Parameters

serviceIdstringrequired

The unique identifier of the service to start.

Error Responses

404Service not found or not accessible

500Failed to start service (server not responding or already running)

Request

curl -X POST "https://api.advps.org/api/v1/services/vps_service_1/start" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "VPS service started successfully",
  "data": {
    "serviceId": "vps_service_1",
    "serviceType": "VPS",
    "status": "STARTED",
    "vmid": "vm1000",
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

POST/api/v1/services/{serviceId}/stop

Stop Service

Stop a running service gracefully.

Parameters

serviceIdstringrequired

The unique identifier of the service to stop.

Error Responses

404Service not found or not accessible

500Failed to stop service (already stopped or server error)

Request

curl -X POST "https://api.advps.org/api/v1/services/vps_service_1/stop" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "VPS service stopped successfully",
  "data": {
    "serviceId": "vps_service_1",
    "serviceType": "VPS",
    "status": "STOPPED",
    "vmid": "vm1000",
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

POST/api/v1/services/{serviceId}/reboot

Reboot Service

Reboot a running service. The service will be briefly unavailable during the restart cycle.

Parameters

serviceIdstringrequired

The unique identifier of the service to reboot.

Error Responses

404Service not found or not accessible

500Failed to reboot service

Request

curl -X POST "https://api.advps.org/api/v1/services/vps_service_1/reboot" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "VPS service rebooted successfully",
  "data": {
    "serviceId": "vps_service_1",
    "serviceType": "VPS",
    "status": "RUNNING",
    "vmid": "vm1000",
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

POST/api/v1/services/{serviceId}/get-ip

Configure IP Address

Assign or configure an IP address for a VPS or Provisional VPS service. Not available for standard Linux containers.

Parameters

serviceIdstringrequired

The unique service identifier (VPS or Provisional VPS only).

Error Responses

404Service not found or not accessible

500Failed to configure IP address

Request

curl -X POST "https://api.advps.org/api/v1/services/vps_service_1/get-ip" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "VPS IP configured successfully",
  "data": {
    "serviceId": "vps_service_1",
    "serviceType": "VPS",
    "status": "IP_CONFIGURED",
    "ip": "192.168.1.100",
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-04T12:00:00.000Z"
}

GET/api/v1/services/{serviceId}/status

Get Service Status

Retrieve the current status and resource usage of a service.

Parameters

serviceIdstringrequired

The unique identifier of the service.

Error Responses

404Service not found or not accessible

500Server is not responding. Please try again in a few minutes.

Request

curl -X GET "https://api.advps.org/api/v1/services/vps_service_1/status" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "VPS status retrieved successfully",
  "data": {
    "serviceId": "vps_service_1",
    "serviceType": "VPS",
    "service": {
      "id": "507f1f77bcf86cd799439099",
      "serviceId": "vps_service_1",
      "ip": "192.168.1.100",
      "username": "Administrator",
      "password": "Xk9mP2nQr7vL",
      "status": "ASSIGNED",
      "runningStatus": "RUNNING",
      "expiryDate": "2026-05-04T12:00:00.000Z",
      "getIP": false,
      "productInfo": {
        "name": "VPS 8GB Plan",
        "cpu": "4 vCPU",
        "ram": "8 GB",
        "storage": "100 GB SSD"
      },
      "os": {
        "name": "Ubuntu 22.04",
        "version": "22.04 LTS"
      }
    },
    "vmStatus": {
      "status": "running",
      "cpuUsage": 0.05,
      "memoryUsage": 0.25,
      "uptime": 86400
    },
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-04T12:00:00.000Z"
}

POST/api/v1/services/{serviceId}/generate-password

Generate Password

Generate a new root/admin password for a service. The service must be running. The new password will be returned once and stored securely.

Parameters

serviceIdstringrequired

The unique identifier of the service.

Error Responses

400Service must be running before generating a password

404Service not found or not accessible

Request

curl -X POST "https://api.advps.org/api/v1/services/vps_service_1/generate-password" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "Password generated successfully",
  "data": {
    "serviceId": "vps_service_1",
    "password": "Xk9mP2nQr7vL",
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

POST/api/v1/services/{serviceId}/rebuild

Rebuild Service

Rebuild a service with a fresh OS image. This is an asynchronous operation — use the returned taskId to poll for completion.

Parameters

serviceIdstringrequired

The unique identifier of the service to rebuild.

Request Body

JSON body with os (string, required) — the operating system identifier to install.

Error Responses

400Missing or invalid os in request body

403Rebuild limit reached. You cannot rebuild this service again.

403Rebuild not available during maintenance window (9:00 AM – 11:30 AM IST)

404Service not found or not accessible

500No OS templates available for the selected OS

Request

curl -X POST "https://api.advps.org/api/v1/services/vps_service_1/rebuild" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"os": "ubuntu-22.04"}'

Response 200 OK

{
  "success": true,
  "data": {
    "serviceId": "vps_service_1",
    "taskId": "uuid-generated-task-id",
    "serviceType": "VPS",
    "status": "PENDING",
    "apiMode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "message": "VPS rebuild initiated successfully"
}

POST/api/v1/services/{serviceId}/reset-mac

Reset MAC Address

Generate and apply a new MAC address to a VPS service. Without an active MAC reset subscription, this can only be done once every 24 hours. Returns the old and new MAC addresses.

Parameters

serviceIdstringrequired

The unique identifier of the VPS service. Only VPS (VM) services are supported.

Error Responses

404Service not found or not a VPS assignment

429MAC reset is only allowed once every 24 hours without a subscription

500Failed to retrieve or apply VM configuration

Request

curl -X POST "https://api.advps.org/api/v1/services/ABCXYZ/reset-mac" \
  -H "x-api-key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "MAC address reset successfully",
  "data": {
    "serviceId": "ABCXYZ",
    "oldMacAddress": "BC:24:11:AA:BB:CC",
    "newMacAddress": "BC:24:11:DD:EE:FF",
    "hasSubscription": false,
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-27T12:00:00.000Z"
}

GET/api/v1/services/task/{taskId}/status

Get Task Status

Poll the status of an asynchronous task, such as a rebuild operation. Poll every 3–5 seconds until status is COMPLETED or FAILED.

Parameters

taskIdstringrequired

The unique task identifier returned by a rebuild request.

Error Responses

404Task not found or not accessible

Request

curl -X GET "https://api.advps.org/api/v1/services/task/uuid-task-id/status" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "Task status retrieved successfully",
  "data": {
    "taskId": "uuid-task-id",
    "status": "COMPLETED",
    "progress": 100,
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

POST/api/v1/services/renew

Renew Services

Renew one or more services on an existing Linux (LXC) or VPS (VM) order. The system automatically detects the order type from the orderId. Services are eligible for renewal when they expire within 5 days or up to 1 day after expiry. Optional per-service validity overrides are supported.

Parameters

orderIdstringrequired

The order ID to renew services for (e.g. LXC260426-9632 or VPS040426-0008).

serviceIdsstring[]required

Array of serviceId values (the human-readable service identifier, not the DB object ID) to renew. All must belong to the specified order.

serviceValiditiesobject[]optional

Optional per-service validity overrides. Each entry: { serviceId: string, validity: number }. Services not listed use the website default validity.

Error Responses

400Some services are not eligible for renewal (expiry outside the -1 to +5 day window, or wrong status)

400Insufficient wallet balance

404Order not found or does not belong to the authenticated seller

404None of the provided serviceIds were found on this order

Request

curl -X POST "https://api.advps.org/api/v1/services/renew" \
  -H "x-api-key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "LXC260426-9632",
    "serviceIds": ["KYOFMI", "ABCXYZ"],
    "serviceValidities": [
      { "serviceId": "KYOFMI", "validity": 30 },
      { "serviceId": "ABCXYZ", "validity": 60 }
    ]
  }'

Response 200 OK

{
  "status": "success",
  "message": "Order renewed successfully",
  "data": {
    "orderId": "LXC260426-9632",
    "orderType": "LXC",
    "renewedCount": 2,
    "baseAmount": 1000,
    "discount": 100,
    "totalAmount": 900,
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-27T12:00:00.000Z"
}

Products

Product Stock

Query real-time product stock levels. Stock is automatically derived from available VM inventory unless manual stock management is enabled for a product.

GET/api/v1/products/stock

List Product Stock

Returns current stock levels for all visible products sorted by stock descending. Supports optional filtering by product type.

Parameters

pageintegeroptional

Page number for pagination. Default: 1.

limitintegeroptional

Results per page, max 100. Default: 10.

typestringoptional

Filter by product type. One of: linux, vps.

Error Responses

400Invalid type value — must be 'linux' or 'vps'

401Missing or invalid API key

Request

curl -X GET "https://api.advps.org/api/v1/products/stock?type=linux&page=1&limit=10" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "Product stock retrieved successfully",
  "data": {
    "stock": [
      {
        "id": "prod_abc123",
        "name": "Linux VPS 4GB",
        "vmType": "LXC",
        "packName": "4GB Linux Pack",
        "stock": 25,
        "stockStatus": "IN_STOCK"
      },
      {
        "id": "prod_def456",
        "name": "Linux VPS 2GB",
        "vmType": "LXC",
        "packName": "2GB Linux Pack",
        "stock": 4,
        "stockStatus": "LOW_STOCK"
      },
      {
        "id": "prod_ghi789",
        "name": "Linux VPS 1GB",
        "vmType": "LXC",
        "packName": "1GB Linux Pack",
        "stock": 0,
        "stockStatus": "OUT_OF_STOCK"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 12,
      "totalPages": 2,
      "hasNext": true,
      "hasPrev": false
    },
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

GET/api/v1/products/stock/{id}

Get Product Stock

Returns the current stock level for a single product by its ID.

Parameters

idstringrequired

The unique product identifier.

Error Responses

404Product not found

401Missing or invalid API key

Request

curl -X GET "https://api.advps.org/api/v1/products/stock/prod_abc123" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "Product stock retrieved successfully",
  "data": {
    "stock": {
      "id": "prod_abc123",
      "name": "Linux VPS 4GB",
      "vmType": "LXC",
      "packName": "4GB Linux Pack",
      "stock": 25,
      "stockStatus": "IN_STOCK"
    },
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

Operating Systems

Query available operating systems for use when purchasing services.

GET/api/v1/os

List Operating Systems

Returns all enabled operating systems. Optionally filter by type to see only VPS or Linux (LXC) compatible OS options.

Parameters

typestringoptional

Filter by service type. One of: vps, lxc. Omit to list all.

Error Responses

400Invalid type value — must be "vps" or "lxc"

401Missing or invalid API key

Request

curl -X GET "https://api.advps.org/api/v1/os?type=vps" \
  -H "x-api-key: sk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "OS list retrieved successfully",
  "data": {
    "os": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "Ubuntu 22.04",
        "type": "VM",
        "price": 0
      },
      {
        "id": "507f1f77bcf86cd799439012",
        "name": "Windows Server 2022",
        "type": "VM",
        "price": 150
      },
      {
        "id": "507f1f77bcf86cd799439013",
        "name": "Debian 12",
        "type": "VM",
        "price": 0
      }
    ],
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12:00:00.000Z"
}

Purchase

Order Services

Place new Linux (LXC) and VPS (VM) orders programmatically. Orders are created in PENDING status and processed automatically.

POST/api/v1/purchase/linux

Purchase Linux Service

Place a new Linux (LXC) order. Validates product availability, calculates pricing with applicable discounts and offers, deducts wallet balance, and creates the order.

Parameters

productIdstringrequired

The product ID to purchase. Use the Products endpoint to find available products.

ramstringrequired

RAM specification. Flexible formats accepted: "4 GB", "8GB", "8", "2.5 GB", "512 MB".

osIdstringrequired

Operating system ID. Use the OS endpoint to list available options.

quantityintegerrequired

Number of services to purchase (1–50).

validityintegeroptional

Validity period in days. Default: 30.

remarkstringoptional

Optional note for the order (max 500 characters).

Error Responses

400Validation failed — missing or invalid fields

400No variation matching the specified RAM

400Insufficient stock

400Insufficient wallet balance

400No pricing available for the selected validity

404Product not found

400Invalid OS selection

Request

curl -X POST "https://api.advps.org/api/v1/purchase/linux" \
  -H "x-api-key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "507f1f77bcf86cd799439011",
    "ram": "4 GB",
    "osId": "507f1f77bcf86cd799439012",
    "quantity": 2,
    "validity": 30,
    "remark": "Client order #1234"
  }'

Response 200 OK

{
  "status": "success",
  "message": "Linux order placed successfully",
  "data": {
    "order": {
      "id": "507f1f77bcf86cd799439099",
      "orderId": "LXC040426-0012",
      "productId": "507f1f77bcf86cd799439011",
      "variationId": "507f1f77bcf86cd799439022",
      "productInfo": {
        "name": "Linux 4GB Plan",
        "os": "Ubuntu 22.04",
        "osPrice": 0,
        "cpu": "2 vCPU",
        "ram": "4 GB",
        "quantity": 2,
        "storage": "50 GB SSD",
        "price": 500
      },
      "validity": 30,
      "baseAmount": 1000,
      "discount": 100,
      "totalAmount": 900,
      "status": "PENDING",
      "remark": "Client order #1234",
      "buyDate": "2026-04-04T12:00:00.000Z"
    },
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-04T12:00:00.000Z"
}

POST/api/v1/purchase/vps

Purchase VPS Service

Place a new VPS (VM) order for a customer. If a user with the provided email already exists, the order is linked to them. If not, a new user account is created and the generated password is returned in the response.

Parameters

productIdstringrequired

The product ID to purchase.

ramstringrequired

RAM specification. Flexible formats: "4 GB", "8GB", "8", "2.5 GB".

osIdstringrequired

Operating system ID for the VPS.

quantityintegerrequired

Number of services to purchase (1–10).

namestringrequired

Customer name (2–100 characters).

emailstringrequired

Customer email address. Used for user account lookup or creation.

validityintegeroptional

Validity period in days. Default: 30.

remarkstringoptional

Optional note for the order (max 500 characters).

Error Responses

400Validation failed — missing or invalid fields

400No variation matching the specified RAM

400Insufficient stock

400Insufficient wallet balance

400A non-customer account with this email already exists

400No pricing available for the selected validity

404Product not found

400Invalid OS selection

Request

curl -X POST "https://api.advps.org/api/v1/purchase/vps" \
  -H "x-api-key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "507f1f77bcf86cd799439011",
    "ram": "8 GB",
    "osId": "507f1f77bcf86cd799439012",
    "quantity": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "validity": 30,
    "remark": "Premium client"
  }'

Response 200 OK

{
  "status": "success",
  "message": "VPS order placed successfully",
  "data": {
    "order": {
      "id": "507f1f77bcf86cd799439099",
      "orderId": "VPS040426-0008",
      "productId": "507f1f77bcf86cd799439011",
      "variationId": "507f1f77bcf86cd799439033",
      "productInfo": {
        "name": "VPS 8GB Plan",
        "os": "Ubuntu 22.04",
        "osPrice": 0,
        "cpu": "4 vCPU",
        "ram": "8 GB",
        "quantity": 1,
        "storage": "100 GB SSD",
        "price": 1200
      },
      "validity": 30,
      "baseAmount": 1200,
      "discount": 150,
      "totalAmount": 1050,
      "status": "PENDING",
      "remark": "Premium client",
      "buyDate": "2026-04-04T12:00:00.000Z",
      "customer": {
        "name": "John Doe",
        "email": "[email protected]"
      }
    },
    "password": "Xk9mP2nQr7vL",
    "userAlreadyExisted": false,
    "message": "New user account created for \"[email protected]\". Password is included in this response.",
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-04T12:00:00.000Z"
}

GET/api/v1/purchase/{orderId}

Get Order Details

Retrieve complete order details including assigned services with credentials. Only API-created orders belonging to the authenticated seller are returned.

Parameters

orderIdstringrequired

The order ID (e.g. LXC040426-0012 or VPS040426-0008).

Error Responses

404Order not found or not accessible

401Missing or invalid API key

Request

curl -X GET "https://api.advps.org/api/v1/purchase/VPS040426-0008" \
  -H "x-api-key: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response 200 OK

{
  "status": "success",
  "message": "Order details retrieved successfully",
  "data": {
    "orderId": "VPS040426-0008",
    "orderType": "VPS",
    "order": {
      "id": "507f1f77bcf86cd799439099",
      "orderId": "VPS040426-0008",
      "status": "ASSIGNED",
      "productInfo": {
        "name": "VPS 8GB Plan",
        "os": "Ubuntu 22.04",
        "osPrice": 0,
        "cpu": "4 vCPU",
        "ram": "8 GB",
        "quantity": 1,
        "storage": "100 GB SSD",
        "price": 1200
      },
      "os": "Ubuntu 22.04",
      "validity": 30,
      "baseAmount": 1200,
      "discount": 150,
      "totalAmount": 1050,
      "buyDate": "2026-04-04T12:00:00.000Z",
      "remark": "Premium client"
    },
    "services": [
      {
        "id": "507f1f77bcf86cd799439100",
        "serviceId": "vps_service_1",
        "ip": "192.168.1.100",
        "status": "ASSIGNED",
        "runningStatus": "RUNNING",
        "expiryDate": "2026-05-04T12:00:00.000Z",
        "password": "Xk9mP2nQr7vL",
        "username": "Administrator",
        "getIP": false
      }
    ],
    "mode": "PRODUCTION",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2026-04-04T12:00:00.000Z"
}

ADVPS API · v1.0 · [email protected]