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

400IP configuration not supported for this service type

404Service not found or not accessible

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": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12: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

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": "Service status retrieved successfully",
  "data": {
    "serviceId": "vps_service_1",
    "serviceType": "VPS",
    "runningStatus": "RUNNING",
    "ip": "192.168.1.100",
    "uptime": 86400,
    "mode": "test",
    "requestId": "req_1706611200000_abc123def"
  },
  "timestamp": "2024-01-30T12: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

403Monthly rebuild limit reached

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"
}

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"
}

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"
}

ADVPS API · v1.0 · [email protected]