REST API Documentation — LinWin Cloud Developer Platform

Overview & Base URL

The LinWin Cloud REST API allows authorized clients to manage OS deployments programmatically. All requests must be made over HTTPS in production and accept/return application/json payloads.

BASE URL: https://linwin.site/api/v1

Authentication

The LinWin Cloud API uses Bearer Tokens to authenticate requests. Provide your secret API token in the HTTP Authorization header:

Authorization: Bearer linwin_sec_997f382a1708465cb...

Security Notice:

Keep your API token confidential. Anyone with access to your Bearer token can launch deployments and consume account credits.

CORE CONCEPT

Callback Token Architecture & Password Flow

Every deployment created in LinWin is provisioned with a unique, high-entropy 48-character cryptographic string called the callback_token. This token serves three essential architectural roles:

1. Telemetry Webhook

The Linux pre-install bash script posts real-time progress updates (POST /webhook/deployment/{callback_token}) so the dashboard and API reflect live progress percentages (0-100%).

2. In-Guest Agent Sync

The pre-installed LinWinAgent Windows service polls GET /vps/agent/{callback_token}/poll every 30s to retrieve pending Administrator password changes without restarting the VPS.

3. Offline KVM Rescue Reset

If Windows is locked or network is unreachable, passing ?token={callback_token} authorizes download of the automated chntpw SAM hive rescue script from any Linux netboot environment.

How to get your callback_token

Via Web UI: Navigate to Deployments History, click "Manage & Password" on any server. The Callback Token is shown with a 1-click Copy button.
Via API Creation: Returned directly in the response of POST /api/v1/deployments under data.callback_token.
Via API Status Query: Returned in GET /api/v1/deployments/{id} and each item in GET /api/v1/deployments.

Rate Limits & Headers

API requests are rate-limited to 60 requests per minute per user account. Every response includes standard rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests permitted within the 1-minute window (default: 60).
X-RateLimit-Remaining	Remaining requests available before throttling takes effect.
Retry-After	Returned with HTTP 429 status indicating seconds to wait before retrying.

GET

/api/v1/user

Retrieve details of the authenticated account, including current deployment credit balance and assigned role.

Request

curl -X GET "https://linwin.site/api/v1/user" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const res = await fetch('https://linwin.site/api/v1/user', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}
response = requests.get('https://linwin.site/api/v1/user', headers=headers)
print(response.json())

Response Example (200 OK)

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Alex Dev",
    "email": "alex@example.com",
    "credits": 5,
    "created_at": "2026-09-10T12:00:00+00:00"
  }
}

GET

/api/v1/os-images

Retrieve the catalog of all available and active Windows OS images, including their exact IDs, versions, and compressed archive sizes. Use the returned id in deployment launches.

Request

curl -X GET "https://linwin.site/api/v1/os-images" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const res = await fetch('https://linwin.site/api/v1/os-images', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}
response = requests.get('https://linwin.site/api/v1/os-images', headers=headers)
print(response.json())

Response Example (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Windows Server 2025 Datacenter",
      "slug": "win-server-2025-dc",
      "version": "24H2",
      "size_human": "4.8 GB",
      "description": "Latest generation server edition with VirtIO drivers pre-baked."
    },
    {
      "id": 2,
      "name": "Windows Server 2022 Datacenter",
      "slug": "win-server-2022-dc",
      "version": "21H2",
      "size_human": "4.2 GB",
      "description": "Enterprise standard high-performance cloud installation."
    },
    {
      "id": 3,
      "name": "Windows 11 Pro",
      "slug": "win-11-pro",
      "version": "23H2",
      "size_human": "5.1 GB",
      "description": "Desktop client OS for remote workstations and testing."
    }
  ]
}

GET

/api/v1/deployments

Retrieve a paginated list of all deployments associated with your account, including live progress percentage, assigned IP, and callback_token.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	The pagination page number.
per_page	integer	15	Number of results per page (max: 100).

Request

curl -X GET "https://linwin.site/api/v1/deployments?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const res = await fetch('https://linwin.site/api/v1/deployments?page=1&per_page=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}
response = requests.get('https://linwin.site/api/v1/deployments', params={'page': 1, 'per_page': 10}, headers=headers)
print(response.json())

Response Example (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 105,
      "callback_token": "cbk_a8f93e1b76c92d849a215fe381204d88e63b419c8491",
      "status": "success",
      "progress": 100,
      "ip_address": "194.38.20.12",
      "os_image": {
        "id": 2,
        "name": "Windows Server 2022 Datacenter",
        "version": "21H2"
      },
      "target_disk": "/dev/sda",
      "error_message": null,
      "started_at": "2026-09-11T00:15:00+00:00",
      "finished_at": "2026-09-11T00:18:12+00:00",
      "duration": "3 minutes",
      "created_at": "2026-09-11T00:14:50+00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 1,
    "last_page": 1
  }
}

GET

/api/v1/deployments/{id}

Query the exact status and real-time installation telemetry of a specific deployment instance by its ID.

Path Parameters

Parameter	Type	Required	Description
id	integer	Required	The deployment instance ID.

Request

curl -X GET "https://linwin.site/api/v1/deployments/105" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const res = await fetch('https://linwin.site/api/v1/deployments/105', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}
response = requests.get('https://linwin.site/api/v1/deployments/105', headers=headers)
print(response.json())

Response Example (200 OK)

{
  "success": true,
  "data": {
    "id": 105,
    "callback_token": "cbk_a8f93e1b76c92d849a215fe381204d88e63b419c8491",
    "status": "in_progress",
    "progress": 65,
    "ip_address": "194.38.20.12",
    "os_image": {
      "id": 2,
      "name": "Windows Server 2022 Datacenter",
      "version": "21H2"
    },
    "target_disk": "/dev/sda",
    "error_message": null,
    "started_at": "2026-09-11T00:15:00+00:00",
    "finished_at": null,
    "duration": null,
    "created_at": "2026-09-11T00:14:50+00:00"
  }
}

POST

/api/v1/deployments

Launch a new automated deployment. Deducts 1 deployment credit from your account and returns the copyable one-liner bash command plus the secret callback_token.

Request Parameters (JSON Body)

Field	Type	Required	Description
os_image_id	integer	Required	Target OS Image ID obtained from `GET /api/v1/os-images`.
rdp_password	string	Required	Desired Administrator RDP password (8-64 characters).
target_disk	string	Optional	Target block device (e.g. `/dev/sda`, `/dev/vda`, `/dev/nvme0n1`). Auto-detected if omitted.

Request

curl -X POST "https://linwin.site/api/v1/deployments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "os_image_id": 2,
    "rdp_password": "P@ssw0rdSecure2026!",
    "target_disk": "/dev/sda"
  }'

const res = await fetch('https://linwin.site/api/v1/deployments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    os_image_id: 2,
    rdp_password: 'P@ssw0rdSecure2026!',
    target_disk: '/dev/sda'
  })
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}
payload = {
    'os_image_id': 2,
    'rdp_password': 'P@ssw0rdSecure2026!',
    'target_disk': '/dev/sda'
}
response = requests.post('https://linwin.site/api/v1/deployments', json=payload, headers=headers)
print(response.json())

Response Example (201 Created)

{
  "success": true,
  "message": "Deployment initiated successfully. Run the installation command on your target VPS.",
  "data": {
    "deployment_id": 106,
    "callback_token": "cbk_49fd28e1c6a287bf104ea205938174ab1987d6e42b10",
    "status": "pending",
    "os_image": "Windows Server 2022 Datacenter",
    "command": "curl -sSL https://linwin.site/deploy/8f2c3d9a10... | bash",
    "target_disk": "/dev/sda",
    "remaining_credits": 4
  }
}

POST

/api/v1/deployments/{id}/password

Change the Administrator password of a running Windows VPS in real time. LinWin enqueues an in-guest command which the pre-installed LinWinAgent service detects and applies within 30-60 seconds without server reboot or downtime.

Request Parameters (JSON Body)

Field	Type	Required	Description
new_password	string	Required	New Administrator RDP password (8-64 characters).

Request

curl -X POST "https://linwin.site/api/v1/deployments/106/password" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "new_password": "NewUltraSecurePass2026!"
  }'

const res = await fetch('https://linwin.site/api/v1/deployments/106/password', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    new_password: 'NewUltraSecurePass2026!'
  })
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}
payload = {
    'new_password': 'NewUltraSecurePass2026!'
}
response = requests.post('https://linwin.site/api/v1/deployments/106/password', json=payload, headers=headers)
print(response.json())

Response Example (200 OK)

{
  "success": true,
  "message": "Real-time password change task queued successfully. The LinWin in-guest agent will apply it within 30-60 seconds.",
  "data": {
    "deployment_id": 106,
    "task_id": 482,
    "callback_token": "cbk_49fd28e1c6a287bf104ea205938174ab1987d6e42b10",
    "status": "pending",
    "agent_poll_url": "https://linwin.site/vps/agent/cbk_49fd28e1c6a287bf104ea205938174ab1987d6e42b10/poll"
  }
}

GET

/api/v1/deployments/{id}/rescue-script

Generate an automated offline KVM rescue script utilizing chntpw and ntfs-3g. Execute this command directly from any Linux netboot or rescue mode to mount the NTFS Windows SAM database and reset forgotten passwords.

Request

curl -X GET "https://linwin.site/api/v1/deployments/106/rescue-script" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const res = await fetch('https://linwin.site/api/v1/deployments/106/rescue-script', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
});
const data = await res.json();
console.log(data);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}
response = requests.get('https://linwin.site/api/v1/deployments/106/rescue-script', headers=headers)
print(response.json())

Response Example (200 OK)

{
  "success": true,
  "data": {
    "deployment_id": 106,
    "callback_token": "cbk_49fd28e1c6a287bf104ea205938174ab1987d6e42b10",
    "rescue_command": "curl -sSL 'https://linwin.site/deployments/106/rescue-script?token=cbk_49fd28e1c6a287bf104ea205938174ab1987d6e42b10' | bash",
    "script_url": "https://linwin.site/deployments/106/rescue-script?token=cbk_49fd28e1c6a287bf104ea205938174ab1987d6e42b10",
    "method": "KVM Offline SAM Hive Modifier (chntpw)",
    "description": "Boot VPS into Linux rescue/netboot mode and execute rescue_command to reset/unlock Windows Administrator credentials."
  }
}

LinWin Cloud Agent & Live In-Guest Sync

Windows instances provisioned by LinWin Cloud configure a lightweight Windows Scheduled Task / background service named LinWinAgent. The agent periodically queries the platform endpoint using its unique callback_token:

POLL ENDPOINT Runs every 30s

GET /vps/agent/{callback_token}/poll

Checks for pending commands (SET_PASSWORD, etc.). Returns has_task: false when idle.

COMPLETE ENDPOINT Post Execution

POST /vps/agent/{callback_token}/complete

Informs LinWin Cloud Cloud that the task was executed successfully by the agent with exit codes and status messages.

Offline KVM SAM Registry Password Reset

If Windows has lost network connectivity, or the guest password was changed outside of LinWin Cloud and forgotten, you can reset it offline with 100% reliability using standard Linux rescue mode (available on Hetzner, OVH, Proxmox, Vultr, Linode, DigitalOcean, etc.).

Step 1: Boot into Linux Rescue Mode

In your cloud provider's console, select "Rescue Mode" (or attach any Debian/Ubuntu netboot ISO) and reboot the VPS. Connect via SSH as root.

Step 2: Run the Automated SAM Reset Command

Retrieve your server's rescue command from the dashboard or API and execute it:

curl -sSL 'https://linwin.site/deployments/{id}/rescue-script?token={callback_token}' | bash

Step 3: Reboot back into Windows

The script mounts the NTFS partition, updates the Windows SAM hive via chntpw, clears account lockouts, and unmounts cleanly. Disable rescue mode and reboot to log in immediately without lockout!

OFFICIAL EXTENSION · v1.1.0

Official WHMCS Provisioning Module

Download WHMCS Module (.zip)

Allow your hosting clients to reinstall Windows and Linux OS on their KVM VPS, perform zero-downtime real-time password changes, and access emergency KVM SAM registry rescue commands directly within their WHMCS Client Area. The module connects securely via your LinWin Cloud Bearer API token.

ZIP Archive Directory Layout:

linwin-whmcs-module-v1.1.0.zip
├── modules/
│   └── servers/
│       └── linwin/
│           └── linwin.php       # Core WHMCS server module (v1.1.0)
├── README.md                    # Technical documentation
└── INSTALL.txt                  # Quick-start configuration notes

Quick Installation Guide:

Download the zip archive using the button above.
Extract the archive directly into your whmcs_root/ directory.
Verify that modules/servers/linwin/linwin.php is in place.
Navigate to System Settings → Products/Services in WHMCS Admin.

Module Configuration Parameters:

LinWin Cloud API URL: https://linwin.site
LinWin Cloud API Token: Your secret Bearer Token (from Billing Area)
Default OS ID: Target Windows OS ID (e.g., 1)
Default RDP Port: 3389
Target Storage Device: auto, /dev/sda, /dev/vda, or /dev/nvme0n1

HTTP Status Codes & Errors

LinWin Cloud uses conventional HTTP response codes to indicate request status. Codes in the 2xx range indicate success; codes in the 4xx range indicate validation or authentication errors; codes in the 5xx range indicate platform issues.

Code	Status	Meaning
200 OK	Success	Request processed successfully.
201 Created	Resource Created	Deployment created and one-liner command ready.
401 Unauthorized	Invalid Token	Missing or invalid Bearer API token.
402 Payment Required	Insufficient Credits	Account has 0 credits. Top up via PayPal, Plisio crypto, or dashboard.
422 Unprocessable	Validation Error	Invalid parameters (e.g. password too short, image ID not found).
429 Too Many Requests	Rate Limited	Request limit exceeded (60 req/min). Inspect `Retry-After` header.

Developer API Documentation

Overview & Base URL

Authentication

Callback Token Architecture & Password Flow

How to get your callback_token

Rate Limits & Headers

/api/v1/user

/api/v1/os-images

/api/v1/deployments

/api/v1/deployments/{id}

/api/v1/deployments

/api/v1/deployments/{id}/password

/api/v1/deployments/{id}/rescue-script

LinWin Cloud Agent & Live In-Guest Sync

Offline KVM SAM Registry Password Reset

Official WHMCS Provisioning Module

HTTP Status Codes & Errors