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.

1 · authenticate
export WH_TOKEN=wh_live_xxxxxxxxxxxxxxxxxxxx

curl -s https://api.wenhost.website/v1/account \
  -H "Authorization: Bearer $WH_TOKEN" | jq '.email, .balance_usd'
2 · discover what you can deploy
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'
3 · create an instance
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"
  }'
4 · wait for it to answer
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.

required header
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.

ScopeGrantsTypical holder
account:readProfile, quota, balanceRead-only
instances:readList and inspect instancesRead-only
instances:writeCreate, resize, reboot, reinstall, releaseDestructive
snapshots:readList snapshots and restore pointsRead-only
snapshots:writeCreate, delete and restore snapshotsReversible
network:writeFirewall rules, IP allocation, PTR recordsCan cut your own access
metrics:readCPU, memory, disk and bandwidth countersRead-only
billing:readInvoices and charges, no payment actionsRead-only
webhooks:writeManage endpoints and secret keysControl 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 example i_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.
200 OK · GET /v1/instances/i_8fk2ld
{
  "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.

ClassRequests / minBurstApplies to
Read600120 / sGET on any resource
Write12020 / sPOST, PATCH
Destructive305 / sDELETE, reinstall, restore
Instance create20 / hour—Per account, quota-bound
Auth failures10 / min—Per source IP, then temporary block
limit headers on every response
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-After when present.
  • Do not retry a DELETE blindly. 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.

list all running Singapore instances
GET /v1/instances?status=running&region=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_more is false. An empty data with a cursor is not the end.
  • Filter operators: repeat a parameter for OR (region=tokyo&region=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.

202 Accepted
{
  "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.

422 Unprocessable Entity
{
  "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"
  }
}
StatusCode exampleMeaningRetry?
200okRead succeeded, or a synchronous write completed.—
201createdResource exists; body carries it.—
202acceptedJob queued; poll the handle or wait for the webhook.—
400malformed_jsonBody could not be parsed.Fix first
401token_revokedMissing, expired or revoked token.Re-authenticate
403insufficient_scopeToken valid, scope not granted.New token
404not_foundNo such resource on this account. Also returned for another tenant's ID, to avoid confirming existence.Check ID
409state_conflictOperation invalid for current state, e.g. resize while provisioning.After state change
422validation_failedWell-formed but semantically impossible.Fix fields
429rate_limitedOver the per-minute budget; Retry-After present.Back off
500internal_errorOur fault. request_id is logged on our side.Yes, with backoff
503region_unavailableControl 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 on POST when you send an Idempotency-Key.
  • A 5xx on 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.

safe retry
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 DELETE on a released instance returns 404, 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.

GET/v1/instances

List instances. Filters: status, region, plan, label.

GET/v1/instances/{id}

Fetch one instance, including activated_at and both refund-window deadlines.

POST/v1/instances

Create and bill an instance. Requires instances:write. Send an idempotency key.

PATCH/v1/instances/{id}

Rename, retag, toggle daily snapshots or off-site replication.

POST/v1/instances/{id}/resize

Change plan. Growing is in place with one reboot, under 5 minutes typical; shrinking disk requires a rebuild.

POST/v1/instances/{id}/power

action: start · stop · restart · force_stop. Prefer stop — it asks the guest OS to shut down cleanly.

POST/v1/instances/{id}/reinstall

Replace the template. Erases the disk. Refuses unless confirm_erase: true, and offers a snapshot in the same call.

POST/v1/instances/{id}/password

Reset root or Administrator password; applies on next boot. Windows instances use this to regain RDP access.

GET/v1/instances/{id}/console

Returns a short-lived VNC URL valid 10 minutes, single-use. Works when SSH or RDP is broken.

DELETE/v1/instances/{id}

Release the instance and stop billing. Disks are destroyed; snapshots survive 7 days for recovery, then are permanent.

POST /v1/instances/{id}/reinstall
{
  "template": "debian-12-x64",
  "ssh_keys": ["ssh-ed25519 AAAAC3Nz... [email protected]"],
  "snapshot_first": true,
  "snapshot_name": "pre-reinstall-2026-10-30",
  "confirm_erase": true
}
POST /v1/instances/{id}/resize
{
  "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.

GET/v1/instances/{id}/snapshots

List restore points, newest first, with size and state.

POST/v1/instances/{id}/snapshots

Create a named manual snapshot. Non-blocking; the instance keeps serving.

POST/v1/snapshots/{snapshot_id}/restore

Roll the disk back to that point. The instance is briefly offline.

DELETE/v1/snapshots/{snapshot_id}

Remove a manual snapshot to reclaim retention slots.

deploy-safe pattern
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.

GET/v1/firewall/profiles

List profiles, including the built-in web-default and deny-all-inbound.

POST/v1/firewall/profiles

Create a profile. Rules are evaluated top-down; first match wins.

POST/v1/firewall/profiles/{id}/rules

Add an inbound or outbound rule.

DELETE/v1/firewall/rules/{id}

Remove one rule without touching the rest of the profile.

POST/v1/instances/{id}/firewall

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.

POST /v1/firewall/profiles
{
  "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

GET/v1/instances/{id}/ips

Allocated addresses, type, and blocklist status where checked.

POST/v1/instances/{id}/ips

Allocate an extra IPv4. Billed monthly as a separate line, non-refundable once assigned.

DELETE/v1/ips/{id}

Return an address to the pool at the end of the current billing period.

PUT/v1/ips/{id}/ptr

Set reverse DNS. Must be a hostname you control; we refuse records impersonating a domain you do not own.

POST/v1/ips/{id}/replace

Request a different address. Free within 7 days of delivery if the one you received is already listed — clause 8 of the Delivery Policy.

PUT /v1/ips/203.0.113.42/ptr
{ "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/vlans then 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/8 pool 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 slugLocationTypical create time
ashburnVirginia, US< 60 s
los-angelesCalifornia, US< 60 s
new-yorkNew York, US< 60 s
torontoOntario, CA< 60 s
londonUnited Kingdom< 60 s
amsterdamNetherlands< 60 s
frankfurtGermany< 60 s
parisFrance< 60 s
milanItaly< 60 s
singaporeSingapore1–5 min
tokyoJapan1–5 min
sydneyAustralia1–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
GET /v1/templates/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.

SlugvCPU · RAM · NVMeTransferIPv4 / IPv6Monthly
vps-nano1 · 2 GB · 40 GB4 TB1 / 64$4.00
vps-starter2 · 4 GB · 80 GB8 TB1 / 64$9.00
vps-pro4 · 8 GB · 160 GB16 TB2 / 64$19.00
vps-enterprise8 · 32 GB · 400 GB32 TB4 / 48$49.00
GET /v1/plans/vps-pro
{
  "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.

GET/v1/instances/{id}/metrics

CPU, memory, disk I/O, connections. Parameters: from, to, resolution = 1m · 5m · 1h · 1d.

GET/v1/instances/{id}/bandwidth

Outbound used against allowance, plus daily series.

GET/v1/instances/{id}/uptime

Measured availability and any qualifying downtime windows — the same figures the SLA credit is calculated from.

GET /v1/instances/i_8fk2ld/bandwidth?period=2026-10
{
  "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_minor is 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_review so 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.

GET/v1/invoices

Past and upcoming invoices, filterable by status and period.

GET/v1/invoices/{id}/pdf

The same PDF emailed to you, for your own archive.

GET/v1/account

Balance, credit, quota, instance count, and the payment methods on file as labels only.

GET /v1/invoices/inv_4412
{
  "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

TypeStatusRefund route
paypalLiveBack to the PayPal transaction
visaComing soonBack to the card
mastercardComing soonBack to the card
amexComing soonBack to the card
stripeComing soonBack 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.

EventFires when
instance.provisioningPayment cleared, build started.
instance.activatedDelivery completed — carries activated_at.
instance.suspendedPowered off, data intact, with the reason.
instance.releasedTerminated; snapshot deadline included.
job.succeeded · job.failedAny asynchronous operation completes.
snapshot.createdManual or daily snapshot ready to restore.
invoice.paid · invoice.failedCharge result, with retry schedule on failure.
abuse.reportedA credible report names your instance — with the evidence, per the Abuse Policy.
maintenance.scheduledRegion maintenance, at least 48 h ahead.
delivered payload
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

Node.js
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.

wenhost CLI
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
main.tf
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 Deprecation response header and a Sunset date 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.
VersionStatusNotes
v1StableDocumented on this page. All new integrations start here.
v1 (beta fields)Opt-inSend WenHost-Beta: gpu-2026-08-01 for preview resources. May change; never used for billed actions.
v0RetiredRemoved 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.

Same 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.

Unmanaged 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.

The 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.

Abuse 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.

Your 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.

Money 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.

SymptomUsual causeFix
401 token_revokedRotated 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_scopeToken created read-only, now used for a write.Create a token with instances:write; keep the read-only one for monitoring.
Create returns 409Quota reached, or an unpaid invoice is blocking new charges.GET /v1/account for quota, GET /v1/invoices?status=open for the blocker.
Instance stuck provisioningRegion 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 callProfile 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 deployNo 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 failingResponding 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 invoiceReading 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.