API Docs
API v1 · stable · included on every plan
Developers · Version 3.0
WenHost API — everything the panel can do.
A versioned JSON REST API over HTTPS for provisioning, resizing, snapshotting and releasing VPS instances. No endpoint is privileged to the web interface: if you can click it, you can call it, and the same Terms, Refund Policy, Delivery Policy and Acceptable Use Policy apply to an API action as to a manual one. API access costs nothing extra and is enabled the moment your first instance is delivered.
Reviewed 30 October 2026 · Base URL https://api.wenhost.website/v1
- Bearer tokens with scopes
- Idempotency keys
- Signed webhooks
- Cursor pagination
Quick start
Four calls from zero to a running server. Create a token first: client area → API & Tokens → Create token. A token is shown once — store it in a secret manager, not in a repository.
export WH_TOKEN=wh_live_xxxxxxxxxxxxxxxxxxxx
curl -s https://api.wenhost.website/v1/account \
-H "Authorization: Bearer $WH_TOKEN" | jq '.email, .balance_usd'
curl -s https://api.wenhost.website/v1/regions -H "Authorization: Bearer $WH_TOKEN" | jq -r '.[].slug'
curl -s "https://api.wenhost.website/v1/templates?os=linux" -H "Authorization: Bearer $WH_TOKEN" | jq -r '.[].slug'
curl -s https://api.wenhost.website/v1/plans -H "Authorization: Bearer $WH_TOKEN" | jq -r '.[].slug'
curl -s -X POST https://api.wenhost.website/v1/instances \
-H "Authorization: Bearer $WH_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: deploy-web-01-2026-10-30" \
-d '{
"name": "web-01",
"plan": "vps-starter",
"region": "singapore",
"template": "ubuntu-24.04-x64",
"ssh_keys": ["ssh-ed25519 AAAAC3Nz... [email protected]"],
"snapshots_enabled": true,
"firewall_profile": "web-default"
}'
curl -s https://api.wenhost.website/v1/instances/id -H "Authorization: Bearer $WH_TOKEN" \
| jq '{status, ipv4, activated_at}'
# status: provisioning → running. Target 45 seconds, committed within 1 hour.
ssh -i ~/.ssh/id_ed25519 deploy@203.0.113.42
Authentication
Every request carries a bearer token in the Authorization header. Tokens are opaque, revocable individually, and never expire silently.
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json # on requests with a body
- TLS only. Plain HTTP is refused. HSTS is set on the API host, and TLS 1.2 is the minimum with 1.3 preferred.
- Prefix tells you the environment.
wh_live_acts on real, billed resources;wh_test_runs against a sandbox that creates no charge and no instance. - No basic auth, no query-string tokens. Credentials in URLs leak into logs and browser history, so we do not accept them at all.
- Every call is logged with token ID, source IP, endpoint, status and UTC timestamp — the same technical data described in clause 3 of the Privacy Policy, retained 90 days.
✕ Token handling rules
- Never commit a token.Use environment variables or a secret manager. If one leaks, revoke it first and investigate second.
- Do not share one token across a team.Issue one per person or per job so a log line identifies an actor.
- Do not embed a token in a mobile or browser client.Anything shipped to a user can be extracted. Proxy through your own backend.
- Do not use a token as an account credential.It grants API actions, not client-area login, and cannot change billing settings.
Rotation
Create the new token, deploy it, then revoke the old one — the API allows two live tokens per scope so rotation is never a downtime event. We may revoke a token we have evidence is compromised and will notify you by email the same day.
Token scopes
Grant the narrowest set that works. A read-only token cannot break production, which makes it the right default for monitoring and CI.
| Scope | Grants | Typical holder |
|---|---|---|
account:read | Profile, quota, balance | Read-only |
instances:read | List and inspect instances | Read-only |
instances:write | Create, resize, reboot, reinstall, release | Destructive |
snapshots:read | List snapshots and restore points | Read-only |
snapshots:write | Create, delete and restore snapshots | Reversible |
network:write | Firewall rules, IP allocation, PTR records | Can cut your own access |
metrics:read | CPU, memory, disk and bandwidth counters | Read-only |
billing:read | Invoices and charges, no payment actions | Read-only |
webhooks:write | Manage endpoints and secret keys | Control plane |
There is deliberately no scope for changing payment methods, email address or password. Those actions require an authenticated client-area session with identity verification, per clause 2 of the Terms of Service. A leaked API token therefore cannot move money or lock you out of your own account.
Conventions
- Format. JSON in and out, UTF-8. Field names are
snake_case; resource identifiers are prefixed, for examplei_8fk2ld,snap_39ja,fw_71bc. - Time. Every timestamp is UTC in ISO 8601 —
2026-10-30T01:22:07Z. This is the same UTC activation timestamp quoted in the Delivery Policy and used by the Refund Policy, so a window computed from the API matches our order log exactly. - Money. Integers in the smallest unit plus a currency field, always
USD.{"amount_minor":1900,"currency":"USD"}is $19.00. No float arithmetic, no rounding surprises. - Bandwidth. Bytes, outbound only. Inbound is never counted and never billed, as stated on the plan pages.
- Booleans and nulls are explicit; a field that does not apply is
null, never omitted to mean something else. - Unknown fields are ignored on write, so adding a field to our response cannot break your client.
{
"id": "i_8fk2ld",
"name": "web-01",
"status": "running",
"plan": {
"slug": "vps-starter",
"vcpu": 2,
"ram_mb": 4096,
"disk_gb": 80,
"transfer_bytes": 8796093022208,
"price_minor": 900,
"currency": "USD"
},
"region": { "slug": "singapore", "country": "SG", "rtt_ms": 18 },
"template": "ubuntu-24.04-x64",
"ipv4": ["203.0.113.42"],
"ipv6_prefix": "2604:abcd:1234::/64",
"snapshots_enabled": true,
"outbound_used_bytes": 412317683712,
"created_at": "2026-10-30T01:20:11Z",
"activated_at": "2026-10-30T01:20:56Z",
"refund_window_closes_at": "2026-11-02T01:20:56Z",
"guarantee_window_closes_at": "2026-11-06T01:20:56Z",
"links": { "self": "/v1/instances/i_8fk2ld" }
}
Rate limits and concurrency
Limits are per token, applied on a sliding minute window, and designed so a normal automation loop never notices them.
| Class | Requests / min | Burst | Applies to |
|---|---|---|---|
| Read | 600 | 120 / s | GET on any resource |
| Write | 120 | 20 / s | POST, PATCH |
| Destructive | 30 | 5 / s | DELETE, reinstall, restore |
| Instance create | 20 / hour | — | Per account, quota-bound |
| Auth failures | 10 / min | — | Per source IP, then temporary block |
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1793323320
Retry-After: 4 # only on 429
Handling a 429 correctly
- Back off exponentially with jitter — 1 s, 2 s, 4 s, 8 s, capped at 60 s. Honour
Retry-Afterwhen present. - Do not retry a
DELETEblindly. Re-read the resource first; a timeout does not mean the action failed. - Poll, do not hammer. For long operations, read the job every 2–5 seconds rather than every response.
- Need more? Ask through the contact form with your use case. Sustained higher limits are available for resellers under clause 15 of the Acceptable Use Policy.
Pagination, filtering, sorting
Collection endpoints return at most 100 items and use an opaque forward cursor. Cursors are stable under concurrent writes, so you never skip or repeat a record mid-scan.
GET /v1/instances?status=running®ion=singapore&per_page=50&sort=-activated_at
GET /v1/instances?cursor=eyJvZmZzZXQiOjUwfQ&status=running
# response envelope
{
"data": [ ... ],
"pagination": {
"per_page": 50,
"next_cursor": "eyJvZmZzZXQiOjEwMH0",
"has_more": true,
"total": 137
}
}
- Stop when
has_moreisfalse. An emptydatawith a cursor is not the end. - Filter operators: repeat a parameter for OR (
region=tokyo®ion=london); comma for exact sets;label:k8s-*for prefix match on names. - Sort fields are documented per resource; a leading
-means descending. - Never parallelise a cursor walk — the next cursor depends on the previous page.
Long operations are asynchronous
Create, resize, reinstall, restore and release return 202 Accepted with a job handle rather than blocking until the hypervisor finishes.
{
"job_id": "job_55kd",
"state": "queued",
"resource": "i_8fk2ld",
"poll": "/v1/jobs/job_55kd"
}
Job states: queued → running → succeeded or failed with a machine-readable code. The matching webhook fires on completion, so polling is a fallback, not the design.
Errors
One predictable envelope, a stable machine code, and a human message you can log. Never parse the message text — it is written for people and may change.
{
"error": {
"code": "template_not_available_in_region",
"message": "windows-server-2025 is not offered in region manila.",
"param": "template",
"request_id": "req_0f81c2a7",
"docs": "https://www.wenhost.website/api-docs#errors"
}
}
| Status | Code example | Meaning | Retry? |
|---|---|---|---|
| 200 | ok | Read succeeded, or a synchronous write completed. | — |
| 201 | created | Resource exists; body carries it. | — |
| 202 | accepted | Job queued; poll the handle or wait for the webhook. | — |
| 400 | malformed_json | Body could not be parsed. | Fix first |
| 401 | token_revoked | Missing, expired or revoked token. | Re-authenticate |
| 403 | insufficient_scope | Token valid, scope not granted. | New token |
| 404 | not_found | No such resource on this account. Also returned for another tenant's ID, to avoid confirming existence. | Check ID |
| 409 | state_conflict | Operation invalid for current state, e.g. resize while provisioning. | After state change |
| 422 | validation_failed | Well-formed but semantically impossible. | Fix fields |
| 429 | rate_limited | Over the per-minute budget; Retry-After present. | Back off |
| 500 | internal_error | Our fault. request_id is logged on our side. | Yes, with backoff |
| 503 | region_unavailable | Control plane in that region is degraded. | Yes, or another region |
- Always log
request_id. Quote it in a ticket and support can find the exact call, including the internal reason, in seconds. - Idempotent retries are safe on
GET,PUT,DELETE, and onPOSTwhen you send anIdempotency-Key. - A
5xxon a create does not mean no instance. List before you retry, or reuse the same idempotency key and the duplicate is collapsed.
Idempotency
Networks fail after the server has already acted. Send the same Idempotency-Key header on any POST and a retry returns the original result instead of creating a second instance — and a second invoice.
POST /v1/instances
Idempotency-Key: provision-2026-10-30-web-01
Authorization: Bearer $WH_TOKEN
# first call → 201, new instance
# retry, same key, same body → 201, identical body, no new charge
# same key, different body → 409 idempotency_key_reuse
- Keys are scoped to your account and token, retained 24 hours. Use a value your workflow can reproduce — a deploy ID, not a random UUID generated after the request.
- Destructive calls are idempotent by design. A second
DELETEon a released instance returns404, not an error cascade.
✓ Where it matters most
- Instance create.Two instances from one retry means two invoices and a surprise at renewal.
- Snapshot create before a deploy.Named snapshots collapse; you get one restore point, not twelve.
- Firewall rule add.Duplicate rules are the classic cause of "why is port 22 open".
- Webhook consumption.Our retries mean you will sometimes receive the same event twice — deduplicate on
event.id.
Instances
The core resource. Lifecycle: provisioning → running → suspended → released. Suspension states are driven by the payment timeline in clause 9 of the Terms of Service, not by API calls.
List instances. Filters: status, region, plan, label.
Fetch one instance, including activated_at and both refund-window deadlines.
Create and bill an instance. Requires instances:write. Send an idempotency key.
Rename, retag, toggle daily snapshots or off-site replication.
Change plan. Growing is in place with one reboot, under 5 minutes typical; shrinking disk requires a rebuild.
action: start · stop · restart · force_stop. Prefer stop — it asks the guest OS to shut down cleanly.
Replace the template. Erases the disk. Refuses unless confirm_erase: true, and offers a snapshot in the same call.
Reset root or Administrator password; applies on next boot. Windows instances use this to regain RDP access.
Returns a short-lived VNC URL valid 10 minutes, single-use. Works when SSH or RDP is broken.
Release the instance and stop billing. Disks are destroyed; snapshots survive 7 days for recovery, then are permanent.
{
"template": "debian-12-x64",
"ssh_keys": ["ssh-ed25519 AAAAC3Nz... [email protected]"],
"snapshot_first": true,
"snapshot_name": "pre-reinstall-2026-10-30",
"confirm_erase": true
}
{
"plan": "vps-pro",
"reboot": true,
"proration": "invoice_now"
}
# 202 → job_71xa
# proration: invoice_now | credit_next | defer
# upgrades are charged the difference for the remaining period
Reinstall and release are the two calls that end a refund right. A reinstall is a fresh delivery of the same instance, so its activation timestamp updates while your billing cycle does not — clause 11 of the Delivery Policy. A release destroys data irrecoverably after the 7-day snapshot window. Both are logged against your token with source IP, and both are rate-limited to 30 per minute precisely because they are hard to undo.
Snapshots
Daily snapshots are included on every plan with 7-day retention. They are our hardware safety net and your rollback button — not a substitute for your own off-platform backup, as clause 11 of the Terms of Service states.
List restore points, newest first, with size and state.
Create a named manual snapshot. Non-blocking; the instance keeps serving.
Roll the disk back to that point. The instance is briefly offline.
Remove a manual snapshot to reclaim retention slots.
snap=$(curl -s -X POST .../snapshots \
-H "Authorization: Bearer $WH_TOKEN" \
-H "Idempotency-Key: deploy-$GIT_SHA" \
-d '{"name":"pre-deploy"}' | jq -r .id)
if ! ./deploy.sh; then
curl -s -X POST ".../snapshots/$snap/restore" -H "Authorization: Bearer $WH_TOKEN"
fi
Retention rules
- Daily automatic snapshots: 7 days, rolling.
- Manual snapshots: also 7 days, so a long-lived archive is the wrong tool — copy data off-platform instead.
- Off-site replication is opt-in per instance and stores copies in a second region.
- After release, snapshots survive 7 days for recovery requests, then are destroyed permanently — including by us.
Restore does not change your billing period, and does not create a new activation timestamp — only a reinstall does.
Firewall
A stateful edge firewall sits in front of every instance, independent of the host firewall inside your OS. Both layers must allow a port for traffic to reach you — which is also why a mistake in one does not expose everything.
List profiles, including the built-in web-default and deny-all-inbound.
Create a profile. Rules are evaluated top-down; first match wins.
Add an inbound or outbound rule.
Remove one rule without touching the rest of the profile.
Attach a profile. The API refuses to apply a profile that would drop your own source IP's SSH or RDP access unless force: true.
{
"name": "web-default",
"rules": [
{ "direction": "in", "protocol": "tcp", "port": 22, "source": "your.office.ip/32", "action": "accept" },
{ "direction": "in", "protocol": "tcp", "port": 80, "source": "0.0.0.0/0", "action": "accept" },
{ "direction": "in", "protocol": "tcp", "port": 443, "source": "0.0.0.0/0", "action": "accept" },
{ "direction": "in", "protocol": "tcp", "port": 3389,"source": "your.office.ip/32", "action": "accept" },
{ "direction": "in", "protocol": "any", "source": "0.0.0.0/0", "action": "drop" }
]
}
Outbound ports 25 and 587 cannot be opened through the API. Mail sending requires prior approval under clause 6 of the Acceptable Use Policy, and approval is a human decision made on your stated volume, list source and authentication records. Any rule attempting to permit them is rejected with 422 port_requires_aup_approval.
IP addresses & reverse DNS
Allocated addresses, type, and blocklist status where checked.
Allocate an extra IPv4. Billed monthly as a separate line, non-refundable once assigned.
Return an address to the pool at the end of the current billing period.
Set reverse DNS. Must be a hostname you control; we refuse records impersonating a domain you do not own.
Request a different address. Free within 7 days of delivery if the one you received is already listed — clause 8 of the Delivery Policy.
{ "hostname": "mail.shop.example.com" }
# 202 → propagates within 5 minutes
# verify: dig -x 203.0.113.42 +short
Private networking
- VLAN membership is available on VPS Pro and above:
POST /v1/vlansthen attach instances. - Private traffic is unmetered and never leaves our backbone — the right place for databases and replication.
- Addresses come from a
10.0.0.0/8pool allocated per account.
DDoS posture
Layer 3/4 filtering with 2 Tbps of scrubbing capacity is always on and cannot be disabled via the API. If your IP is temporarily null-routed to protect neighbours during a flood, GET /v1/ips/{id} reports routing: null_routed with start and expected end times — the transparency rule in clause 9 of the Abuse Policy.
Regions & templates
Read these lists at runtime instead of hardcoding them. Availability changes with stock, and a template retired upstream is removed here first.
| Region slug | Location | Typical create time |
|---|---|---|
ashburn | Virginia, US | < 60 s |
los-angeles | California, US | < 60 s |
new-york | New York, US | < 60 s |
toronto | Ontario, CA | < 60 s |
london | United Kingdom | < 60 s |
amsterdam | Netherlands | < 60 s |
frankfurt | Germany | < 60 s |
paris | France | < 60 s |
milan | Italy | < 60 s |
singapore | Singapore | 1–5 min |
tokyo | Japan | 1–5 min |
sydney | Australia | 1–5 min |
Fifteen OS templates
- ubuntu-20.04-x64
- ubuntu-22.04-x64
- ubuntu-24.04-x64
- debian-11-x64
- debian-12-x64
- centos-7-x64
- almalinux-8-x64
- almalinux-9-x64
- rockylinux-8-x64
- rockylinux-9-x64
- fedora-41-x64
- fedora-42-x64
- windows-server-2019
- windows-server-2022
- windows-server-2025
{
"slug": "windows-server-2025",
"os": "windows",
"license_required": true,
"license_addon_minor": 1200,
"license_currency": "USD",
"refundable_after_issue": false,
"eol": null
}
Windows templates return license_required: true. The add-on is billed monthly, issued by the vendor, and is non-refundable once issued — the same rule the Refund Policy states, surfaced in the API so your automation cannot create a charge a customer will dispute.
Plans
Prices come from the same catalogue the checkout uses, in USD minor units. Never cache a price longer than your session — the API is the source of truth at order time.
| Slug | vCPU · RAM · NVMe | Transfer | IPv4 / IPv6 | Monthly |
|---|---|---|---|---|
vps-nano | 1 · 2 GB · 40 GB | 4 TB | 1 / 64 | $4.00 |
vps-starter | 2 · 4 GB · 80 GB | 8 TB | 1 / 64 | $9.00 |
vps-pro | 4 · 8 GB · 160 GB | 16 TB | 2 / 64 | $19.00 |
vps-enterprise | 8 · 32 GB · 400 GB | 32 TB | 4 / 48 | $49.00 |
{
"slug": "vps-pro",
"vcpu": 4, "ram_mb": 8192, "disk_gb": 160,
"transfer_bytes": 17592186044416,
"port_mbps": 1000,
"ipv4_count": 2, "ipv6_prefix": 64,
"private_vlan": true,
"price_minor": 1900, "currency": "USD",
"annual_discount_pct": 20,
"setup_fee_minor": 0,
"renewal_price_minor": 1900,
"available_regions": ["ashburn","amsterdam","frankfurt","singapore","tokyo"]
}
renewal_price_minor is always equal to price_minor. That field exists because a list price that doubles on renewal is the practice we do not engage in — clause 6 of the Terms of Service and clause 14 of the Payment Options page say the same thing in prose.
Usage & metrics
Time-series counters for capacity planning and billing reconciliation. Inbound bytes are reported for information and are never billed.
CPU, memory, disk I/O, connections. Parameters: from, to, resolution = 1m · 5m · 1h · 1d.
Outbound used against allowance, plus daily series.
Measured availability and any qualifying downtime windows — the same figures the SLA credit is calculated from.
{
"period": "2026-10",
"outbound_used_bytes": 412317683712,
"outbound_allowance_bytes": 8796093022208,
"inbound_bytes": 1904821043200,
"percent_used": 4.7,
"overage_charged_minor": 0,
"fair_use_review": false
}
✓ What the numbers commit to
- No silent overage.
overage_charged_minoris 0 and stays 0. Sustained use far beyond allowance triggers a conversation with numbers, never a surprise invoice. - 30 days' notice on any change.Clause 8 of the Acceptable Use Policy, exposed here as
fair_use_reviewso you see it coming. - Retention 90 days.Metrics older than that are aggregated to daily, matching the Privacy Policy schedule.
- Same source as your invoice.One number, two views — no reconciliation gap.
Billing — read-only
There is no API to charge, refund or change a payment method. Those actions require an authenticated client-area session with identity verification, so a leaked token cannot move money.
Past and upcoming invoices, filterable by status and period.
The same PDF emailed to you, for your own archive.
Balance, credit, quota, instance count, and the payment methods on file as labels only.
{
"id": "inv_4412",
"number": "WH-2026-04412",
"status": "paid",
"currency": "USD",
"subtotal_minor": 1900,
"tax_minor": 0,
"total_minor": 1900,
"method": { "type": "paypal", "label": "PayPal ····42" },
"issued_at": "2026-10-30T01:21:02Z",
"period_start": "2026-11-01",
"period_end": "2026-12-01",
"lines": [
{ "description": "vps-pro monthly — web-01 (singapore)", "amount_minor": 1900 }
]
}
Payment methods, as the API sees them
| Type | Status | Refund route |
|---|---|---|
paypal | Live | Back to the PayPal transaction |
visa | Coming soon | Back to the card |
mastercard | Coming soon | Back to the card |
amex | Coming soon | Back to the card |
stripe | Coming soon | Back to the card |
A method marked coming soon cannot be attached or charged. Attempting it returns 422 method_not_available — the API will never let automation reach for a route that does not exist yet, which is how a checkout failure becomes a payment-network claim.
Webhooks
Event delivery instead of polling. Your endpoint receives a JSON POST, must verify the signature, must respond 2xx within 10 seconds, and must tolerate duplicates.
| Event | Fires when |
|---|---|
instance.provisioning | Payment cleared, build started. |
instance.activated | Delivery completed — carries activated_at. |
instance.suspended | Powered off, data intact, with the reason. |
instance.released | Terminated; snapshot deadline included. |
job.succeeded · job.failed | Any asynchronous operation completes. |
snapshot.created | Manual or daily snapshot ready to restore. |
invoice.paid · invoice.failed | Charge result, with retry schedule on failure. |
abuse.reported | A credible report names your instance — with the evidence, per the Abuse Policy. |
maintenance.scheduled | Region maintenance, at least 48 h ahead. |
POST https://api.yourapp.com/wenhost/webhook
Wh-Signature: t=1793323320,v1=5257a869e7...
Wh-Event-Id: evt_9a1c
{
"id": "evt_9a1c",
"type": "instance.activated",
"created_at": "2026-10-30T01:20:56Z",
"data": {
"id": "i_8fk2ld",
"region": "singapore",
"ipv4": "203.0.113.42",
"activated_at": "2026-10-30T01:20:56Z",
"refund_window_closes_at": "2026-11-02T01:20:56Z"
}
}
Verify the signature
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const [t, v] = Object.fromEntries(
header.split(',').map(p => p.split('='))
);
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const ok = crypto.timingSafeEqual(
Buffer.from(v), Buffer.from(expected)
);
return ok && Math.abs(Date.now()/1000 - t) < 300;
}
- Compare in constant time and reject events older than 5 minutes — that stops replay.
- Deduplicate on
Wh-Event-Id. We retry, so at-least-once delivery is the guarantee, not at-most-once. - Retry policy: 1 min, 5 min, 30 min, 2 h, 6 h, 24 h. After that the endpoint is marked failing and every event is retained for manual replay for 7 days.
- Respond fast, work later. Enqueue and return
200; do slow work outside the request or you will trip the timeout and receive duplicates. - Rotate the signing secret from the panel; both secrets are accepted for 24 hours so rotation is not an outage.
CLI & Terraform
Both wrap the same API and add nothing to it, so anything you script here works with a token and the base URL above.
brew install wenhost/tap/wenhost
# or: curl -fsSL https://get.wenhost.website | sh
wenhost auth login --token-env WH_TOKEN
wenhost instances ls --status running --region singapore
wenhost instances create --plan vps-starter --region tokyo \
--template debian-12-x64 --name api-02 --snapshot daily
wenhost snapshots create i_8fk2ld --name pre-deploy
wenhost ssh i_8fk2ld
wenhost usage i_8fk2ld --period 2026-10
terraform {
required_providers {
wenhost = { source = "wenhost/wenhost", version = "~> 1.2" }
}
}
provider "wenhost" {
alias = "sg"
region = "singapore"
}
resource "wenhost_instance" "web" {
for_each = toset(["web-01", "web-02"])
provider = wenhost.sg
name = each.key
plan = "vps-pro"
template = "ubuntu-24.04-x64"
ssh_keys = [var.deploy_key]
snapshots_enabled = true
firewall_profile = "web-default"
lifecycle { prevent_destroy = true }
}
Versioning & deprecation
The version lives in the path — /v1. Additive changes ship without a version bump; anything that could break a client requires a new version and a written sunset period.
- Never breaking in
/v1: removing or renaming a field, changing a type, tightening validation on a previously valid request, changing an error code you already handle, or repurposing a status code. - Allowed without notice: new endpoints, new optional fields, new enum values on read, new scopes, and improved messages.
- Code defensively: ignore unknown fields, and treat an unrecognised enum value as a state to log rather than a crash.
- Deprecation: a field or endpoint gains a
Deprecationresponse header and aSunsetdate at least 180 days out, announced by email and on the status page — the same 14-day minimum used for policy changes, extended because code takes longer to migrate than a document.
| Version | Status | Notes |
|---|---|---|
v1 | Stable | Documented on this page. All new integrations start here. |
v1 (beta fields) | Opt-in | Send WenHost-Beta: gpu-2026-08-01 for preview resources. May change; never used for billed actions. |
v0 | Retired | Removed 2024-06-30. Requests return 410 gone with a migration pointer. |
Security and policy, in API terms
Automation does not create a separate set of rules. These are the policy points that surface as API behaviour.
1Same windows, same clock
An instance created by the API carries the identical activated_at timestamp and the same 72-hour refund window and 7-day first-order guarantee as one created by clicking. The windows are returned on the resource so your code can see them.
2Unmanaged still means unmanaged
The API gives you power, not management. We keep the platform healthy and diagnose to the OS boundary; your software is yours — clause 4 of the Terms of Service.
3The AUP is enforced at the edge
Port 25/587 approval, no open proxies, no scanning ranges you do not own, declared mining. Rules that would violate it are rejected rather than accepted and punished later.
4Abuse reaches you, not just us
A credible report naming your instance triggers abuse.reported with the evidence and the notice window from clause 17 of the Abuse Policy. You learn at the same moment we do.
5Your data stays yours
We do not read instance content through the API — there is no endpoint that does. Token and request logs are technical data handled under the Privacy Policy, retained 90 days.
6Money actions need a human session
No refund, no payment-method change, no account email change via API. Refunds follow the original payment method, and only a verified request can start one.
Rate limits are also an abuse control. The create cap and the auth-failure block exist to stop a stolen credential from spinning up instances on someone else's bill — the same fraud-screening purpose described in clause 16 of the Payment Options page. If your legitimate automation needs more, ask; do not work around it with multiple tokens.
Troubleshooting
The calls that go wrong most often, and the fix.
| Symptom | Usual cause | Fix |
|---|---|---|
401 token_revoked | Rotated or compromised token, or a wh_test_ key against the live host. | Check the prefix, then issue a new token with the same scopes and revoke the old one. |
403 insufficient_scope | Token created read-only, now used for a write. | Create a token with instances:write; keep the read-only one for monitoring. |
Create returns 409 | Quota reached, or an unpaid invoice is blocking new charges. | GET /v1/account for quota, GET /v1/invoices?status=open for the blocker. |
Instance stuck provisioning | Region capacity wave, or a Windows licence issue. | Poll the job. Past the commitment in clause 4 of the Delivery Policy, you are owed a correction or a full refund that does not use your guarantee. |
| SSH refused after a firewall call | Profile applied without your source IP allowed. | Use GET /v1/instances/{id}/console for VNC access, then fix the rule. The API blocks this by default unless force: true. |
| Duplicate instances from one deploy | No Idempotency-Key, and the client retried on timeout. | Send a reproducible key per deploy; release the duplicate and note the credit on the next invoice. |
| Webhook endpoint marked failing | Responding slower than 10 s, or verifying the raw body after parsing it. | Verify against the exact bytes received, return 200 immediately, process asynchronously. |
| Numbers do not match the invoice | Reading inbound_bytes, or summing a period with a partial month. | Only outbound_used_bytes is billed. Use ?period=YYYY-MM for a closed period. |
Include request_id in every report. It is on every response header and in every error body, and it lets support find your exact call — the same evidence-first principle the Abuse Policy asks of external reporters.
Developer questions, answered
Short answers, each pointing at the section or policy that governs it.
Does API access cost extra?
No. It is included on every plan, from VPS Nano at $4/month, with no per-request charge and no minimum spend. Rate limits exist for fairness, not for upselling.
Is there a sandbox?
Yes — a token prefixed wh_test_ runs against a sandbox that creates no instance and no invoice, so you can exercise create, resize and release logic safely. Sandbox resources are cleared weekly.
Can I create instances for my own customers?
Yes, and you are responsible for their conduct under clause 15 of the Acceptable Use Policy. Public resale of capacity to anonymous buyers needs a separate agreement — tell us before you build it.
What happens to a running instance if my payment fails?
The API mirrors the panel timeline exactly: notice on day 0, grace to day 3, suspension on day 4 with data intact, release on day 11. invoice.failed fires on day 0 so your automation can alert before your users notice.
Can I delete an instance by accident?
You can, which is why DELETE is rate-limited, requires instances:write, and is irreversible after the 7-day snapshot window. Terraform users should set prevent_destroy. There is no undelete endpoint.
Do you support IPv6-only instances?
Every plan includes an IPv6 prefix alongside IPv4. IPv6-only is available on request for customers with their own transit arrangements — ask with your routing plan.
How do I claim an SLA credit programmatically?
Read GET /v1/instances/{id}/uptime and open a ticket within 14 days of the incident. Credits are 5% or 10% of the monthly fee by severity, capped at one month, applied to the next invoice — and they never consume your money-back guarantee.
Is there a GraphQL or gRPC interface?
No. REST with JSON is the contract, and keeping one surface is what lets the API, the panel and the invoice agree on the same numbers. Beta preview endpoints are announced on the status page.
Building something against the API?
Tell us what you are automating and we will sanity-check the design before you ship it — quota, webhook reliability, idempotency, or a higher limit for a reseller platform. Include a request_id if something already failed, and support can find the exact call.
Reviewed 30 October 2026 · API v1. Field names, limits and endpoints on this page are the published contract for v1; breaking changes require a new version and a 180-day sunset. Refund windows, delivery commitments, acceptable use and data handling are governed by the Terms of Service, Refund Policy, Delivery Policy, Acceptable Use Policy, Abuse Policy and Privacy Policy as published on this site.
