Getting started

Use the ZYNOO API to order VPS hosting and manage servers from your own application. You can also manage existing VPSs without placing orders through the API.

Base URL

https://bill.zynoo.com/vps-api/index.php

Make your first request

Create an API credential under API Access in your reseller account.
Follow Authentication to sign a request.
Call GET /v1/vps to list your VPSs. Save each remote_service_id to use in later requests.

Set up authentication →List and manage your VPSs →

Requests and responses

Use HTTPS and send request bodies as JSON. Responses contain ok: true on success, or ok: false with an error object.

Every request except /v1/ping needs the authentication headers. Examples on the following pages show the URL and body; add those headers to your request. Response examples show selected fields. IDs, prices and addresses are illustrative.

Check the API

A public availability check. No API credential is required.

GET/v1/ping

Scope: None

cURL

curl 'https://bill.zynoo.com/vps-api/index.php/v1/ping'

Response · HTTP 200

Example response

{
  "ok": true,
  "api": "v1",
  "server_time": 1700000000
}

Your account

Get your balance, currency, reseller discount and API permissions.

GET/v1/account

Scope: account:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/account

Response · HTTP 200

Example response

{
  "ok": true,
  "account": {
    "currency": {
      "code": "USD"
    },
    "prepaid_credit": {
      "balance": 100
    },
    "tier": {
      "name": "Example tier",
      "discount_percent": 10
    },
    "permissions": {
      "new_orders": true,
      "lifecycle": true
    }
  }
}

Authentication

Your API Access ID identifies your account. Your secret signs each request; it is never sent to the API. Make calls from your backend and keep both values out of browser code.

Required headers

Header	What to send
`X-VR-Key`	Your API Access ID.
`X-VR-Timestamp`	Current Unix time in seconds. Keep your server clock accurate; the default tolerance is five minutes.
`X-VR-Nonce`	A fresh random string for each request: 12–120 letters, digits, or `._~-`.
`X-VR-Signature-Version`	`2`
`X-VR-Signature`	The hexadecimal HMAC-SHA256 signature described below.
`Content-Type`	`application/json` when sending a body.

For orders and reinstalls, also send X-Idempotency-Key: a unique action key you save with the request. Reuse it only when retrying that same request. Use 1–128 letters, digits, or ._:-.

Create the signature

Join these six values with a single LF newline (\n) between them, then calculate HMAC-SHA256 using your API secret:

Signature input

timestamp
nonce
HTTP_METHOD
/v1/request/path
SHA256(request_body)
idempotency_key

Use the uppercase method and decoded path, such as /v1/vps. Exclude the domain, /vps-api/index.php and query string. Hash the exact body bytes you send; for GET, hash an empty string. If there is no action key, leave the sixth value empty. Do not append another newline.

Complete PHP example: list your VPSs

Requires PHP 8.1+ with cURL. Set ZYNOO_API_KEY and ZYNOO_API_SECRET in your server environment, then run this example. It makes one read-only request.

PHP

$key = (string) getenv('ZYNOO_API_KEY');
$secret = (string) getenv('ZYNOO_API_SECRET');
if ($key === '' || $secret === '') {
    throw new RuntimeException('Set API credentials on your backend.');
}
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(18));
$path = '/v1/vps';
$canonical = implode("\n", [
    $timestamp, $nonce, 'GET', $path, hash('sha256', ''), ''
]);
$signature = hash_hmac('sha256', $canonical, $secret);

$ch = curl_init('https://bill.zynoo.com/vps-api/index.php' . $path . '?limit=100');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 45,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-VR-Key: ' . $key,
        'X-VR-Timestamp: ' . $timestamp,
        'X-VR-Nonce: ' . $nonce,
        'X-VR-Signature-Version: 2',
        'X-VR-Signature: ' . $signature,
    ],
]);
$raw = curl_exec($ch);
$httpStatus = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($raw === false) throw new RuntimeException('API connection failed.');
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($httpStatus !== 200 || empty($result['ok'])) {
    throw new RuntimeException($result['error']['message'] ?? 'API request failed.');
}
foreach ($result['services'] as $vps) {
    echo $vps['remote_service_id'] . ': ' . $vps['status'] . PHP_EOL;
}

Permissions

Enable the scopes needed by your integration when creating the credential. Each endpoint below lists its scope. If you set an IP allowlist, use the public IP of the server making your API calls.

Plans & orders

Choose a plan, read its available options, then submit an order. Use the values returned by the API for operating systems and other options.

List plans

Get the plans available to your account, including prices in your account currency.

GET/v1/plans

Scope: catalog:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/plans

Response · HTTP 200

Example response

{
  "ok": true,
  "currency": "USD",
  "plans": [
    {
      "pid": 10,
      "name": "Example VPS",
      "prices": {
        "monthly": {
          "recurring": 12,
          "setup": 0
        }
      }
    }
  ]
}

Plan options

Replace {pid} with a plan’s pid. The provisioning object lists required fields and valid choices.

GET/v1/plans/{pid}

Scope: catalog:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/plans/10

Response · HTTP 200

Example response

{
  "ok": true,
  "currency": "USD",
  "plan": {
    "pid": 10,
    "name": "Example VPS",
    "prices": {
      "monthly": {
        "recurring": 12,
        "setup": 0
      }
    },
    "provisioning": {
      "operating_system": {
        "required": true,
        "choices": [
          {
            "value": "ubuntu-example",
            "label": "Example Ubuntu image"
          }
        ]
      },
      "configurable_options": [
        {
          "name": "number_of_ips",
          "required": true,
          "choices": [
            {
              "value": "1",
              "label": "1 IP"
            },
            {
              "value": "2",
              "label": "2 IPs"
            }
          ]
        }
      ],
      "custom_fields": []
    }
  }
}

Use prices to find available billing cycles. Check the required flags for hostname, root_password, operating_system, configurable_options and custom_fields. Base recurring prices include your discount; option prices are before that discount. The invoice contains the final total, including setup fees and applicable taxes.

Order a VPS

Create an order using a plan ID and its options. Your account must have ordering enabled. Payment or available credit determines when provisioning can proceed.

POST/v1/orders

Scope: services:create

Body field	Value
`client_service_key`	Required. Your unique, permanent ID for this VPS, e.g. `store:42`. Use 1–128 letters, digits or `._:-`.
`pid`	Required. Plan ID.
`billing_cycle`	An offered billing cycle; defaults to `monthly`.
`hostname`	If required: a DNS hostname, up to 255 characters.
`root_password`	If required: 8–128 UTF-8 bytes, without control characters.
`operating_system`	The selected OS `value` from the plan.
`configurable_options / custom_fields`	Objects containing the required field names and their values.

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/orders
Content-Type: application/json
X-Idempotency-Key: order-42

{
  "client_service_key": "store:42",
  "pid": 10,
  "billing_cycle": "monthly",
  "hostname": "vps.example.net",
  "root_password": "REPLACE_WITH_PRIVATE_PASSWORD",
  "operating_system": "ubuntu-example",
  "configurable_options": {
    "number_of_ips": "2"
  }
}

In this example, number_of_ips: "2" requests two IP addresses. Replace the example field names and values with those returned for your plan.

Response · HTTP 201

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "client_service_key": "store:42",
    "status": "Pending",
    "hostname": "vps.example.net",
    "dedicated_ip": "",
    "assigned_ips": [],
    "reseller_hold": false,
    "supplier_hold": false,
    "provisioning_state": "awaiting_payment"
  }
}

A new order returns 201. Save service.remote_service_id and use Get a VPS to check its status. Pending means it is not ready yet; Active means the service is active.

If the request times out, look up the VPS using your original client_service_key. If you retry, keep the same client key, action key and body. A repeated request returns the existing result with 200; changing its body returns 409.

Your VPSs

Use the remote_service_id from your VPS list in place of {reference}. For example: ZV-ABC-0101. Your original client_service_key is also accepted. URL-encode the reference when building the path.

List your VPSs

Returns the VPS records belonging to your account. The list includes every service status unless you add a filter.

GET/v1/vps

Scope: services:read

Query parameter	Value
`status`	Optional: `active`, `pending`, `suspended`, `terminated` or `error`.
`limit`	Records per page: 1–250. Default: 100.
`cursor`	The `next_cursor` returned by the previous page.

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps?status=active&limit=100

Response · HTTP 200

Example response

{
  "ok": true,
  "services": [
    {
      "remote_service_id": "ZV-ABC-0101",
      "client_service_key": "store:42",
      "status": "Active",
      "hostname": "vps.example.net",
      "dedicated_ip": "198.51.100.10",
      "assigned_ips": [],
      "reseller_hold": false,
      "supplier_hold": false
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": false,
    "next_cursor": null
  }
}

When has_more is true, request the next page using cursor and the same status filter. Service status and power state are separate: an Active VPS can be powered off.

Get a VPS

Get the hostname, IP addresses, service status and latest reinstall operation for one VPS.

GET/v1/vps/{reference}

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101

Response · HTTP 200

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "client_service_key": "store:42",
    "status": "Active",
    "hostname": "vps.example.net",
    "dedicated_ip": "198.51.100.10",
    "assigned_ips": [],
    "reseller_hold": false,
    "supplier_hold": false
  }
}

Get multiple VPSs

Read up to 100 VPS records in one request. Results are keyed by the reference you send. Missing or unowned references appear in errors with service_not_found.

POST/v1/vps/query

Scope: services:read

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/query
Content-Type: application/json

{
  "references": [
    "ZV-ABC-0101"
  ]
}

Response · HTTP 200

Example response

{
  "ok": true,
  "services": {
    "ZV-ABC-0101": {
      "remote_service_id": "ZV-ABC-0101",
      "client_service_key": "store:42",
      "status": "Active",
      "hostname": "vps.example.net",
      "dedicated_ip": "198.51.100.10",
      "assigned_ips": [],
      "reseller_hold": false,
      "supplier_hold": false
    }
  },
  "errors": {}
}

Resource usage

Read CPU, memory, disk, bandwidth and power state. The VPS must be Active and have no suspension holds.

GET/v1/vps/{reference}/metrics

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/metrics

Response · HTTP 200

Example response

{
  "ok": true,
  "metrics": {
    "available": true,
    "power_state": "online",
    "cpu_percent": 2.4,
    "memory_used_mb": 512,
    "memory_total_mb": 2048,
    "disk_used_gb": 4.2,
    "disk_total_gb": 40,
    "cache_seconds": 1800,
    "collected_at": "2026-09-21 10:00:00",
    "status_collected_at": "2026-09-21 10:05:00",
    "server_timezone": "UTC"
  }
}

Resource readings normally refresh every 30 minutes. Use collected_at and cache_seconds to show their age. A new VPS may need a minute or two before readings become available. Display unavailable or null values as unavailable, not zero.

Refresh power state

Get a fresh online/offline reading. This does not force new CPU, memory or disk readings.

GET/v1/vps/{reference}/metrics/refresh

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/metrics/refresh

The response uses the same metrics object. power_state is online, offline, suspended or unknown; status_collected_at is its timestamp. Timestamps use server_timezone.

Older service references

Get a ZYNOO reference

Convert an older reference to the current ZYNOO format. Send {}. Returns service.remote_service_id; an existing ZYNOO reference is returned unchanged. Requires services:read and services:reference:write.

POST/v1/vps/{reference}/reference

Scope: services:reference:write

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reference
Content-Type: application/json

{}

Power & access

Use these requests to control a VPS or change its password. Your credential needs the listed scope, and your account must allow VPS management. Check customer ownership in your application before sending a command.

Power controls

The VPS must be Active, without a suspension hold or an unfinished reinstall. Send an empty JSON object {}.

Endpoint · scope: power:write	Action
`POST /v1/vps/{reference}/start`	Start the VPS.
`POST /v1/vps/{reference}/stop`	Shut down the VPS gracefully.
`POST /v1/vps/{reference}/reboot`	Restart the VPS.
`POST /v1/vps/{reference}/poweroff`	Force the VPS off. Unsaved data may be lost.

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reboot
Content-Type: application/json

{}

Response · HTTP 200

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "client_service_key": "store:42",
    "status": "Active",
    "hostname": "vps.example.net",
    "dedicated_ip": "198.51.100.10",
    "assigned_ips": [],
    "reseller_hold": false,
    "supplier_hold": false
  }
}

A successful response acknowledges the command. Call Refresh power state to check the result.

Change the root password

Set a new password for an Active VPS without holds or an unfinished reinstall. Use 8–128 UTF-8 bytes without control characters.

POST/v1/vps/{reference}/password

Scope: password:write

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/password
Content-Type: application/json

{
  "password": "REPLACE_WITH_PRIVATE_PASSWORD"
}

Returns 200 with ok: true and a service object. The password is not returned.

Suspend or terminate a VPS

Scope: lifecycle:write. Send {} to each endpoint. These actions return 200 with ok: true and the updated service.

Endpoint	Action
`POST /v1/vps/{reference}/suspend`	Suspend the VPS.
`POST /v1/vps/{reference}/unsuspend`	Remove your suspension. A ZYNOO hold must be resolved separately.
`POST /v1/vps/{reference}/terminate`	Permanently delete the VPS and its data. Confirm with the customer first.

OS reinstall

Reinstalling a VPS replaces its operating system and deletes its existing data. Ask the customer to confirm before continuing. The service must be Active, without holds or an unfinished reinstall, and reinstall must be enabled for your account.

1. Choose an operating system

Get the operating systems available for this VPS. Use the returned value in your reinstall request; it may differ from the value used when ordering. Your account must allow VPS management.

GET/v1/vps/{reference}/reinstall-options

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reinstall-options

Response · HTTP 200

Example response

{
  "ok": true,
  "options": [
    {
      "value": "1001",
      "label": "Example Ubuntu image",
      "distro": "ubuntu"
    }
  ],
  "collected_at": "2026-09-21 10:00:00"
}

2. Reinstall the VPS

Send the selected OS value, a new password and the VPS’s current hostname. All three fields are required. Allow at least 150 seconds for this request.

POST/v1/vps/{reference}/reinstall

Scope: reinstall:write

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reinstall
Content-Type: application/json
X-Idempotency-Key: reinstall-42-1

{
  "operating_system": "1001",
  "password": "REPLACE_WITH_PRIVATE_PASSWORD",
  "confirmation_hostname": "vps.example.net"
}

The password must contain 8–128 UTF-8 bytes without control characters. confirmation_hostname must match the current hostname after trimming whitespace. Save your action key with this request.

Response · HTTP 202

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "latest_operation": {
      "id": "op_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
      "type": "reinstall",
      "state": "accepted",
      "requires_review": false,
      "message": "Reinstall request accepted; waiting for completion."
    }
  }
}

202 means the request was processed, not that installation is complete. Check service.latest_operation.state before showing success.

3. Check progress

Use the operation ID from service.latest_operation.id. Reinstall starts immediately; completion reporting can take a few minutes.

GET/v1/operations/{operation_id}

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/operations/op_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1

Response · HTTP 200

Example response

{
  "ok": true,
  "operation": {
    "id": "op_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "type": "reinstall",
    "state": "succeeded",
    "requires_review": false,
    "message": "Reinstall completed."
  }
}

State	Meaning
`running / accepted`	Still in progress.
`succeeded`	Installation completed.
`failed`	The request failed; read the message.
`unknown`	The outcome needs review. Contact support before retrying.

Errors & limits

When a request fails, check the HTTP status and the error.code field. Include request_id when contacting support.

Example error

{
  "ok": false,
  "error": {
    "code": "service_not_found",
    "message": "Service not found.",
    "request_id": "example-request-id"
  }
}

HTTP status codes

Status	What to do
400 / 413 / 415	Check JSON formatting, the 256 KiB body limit and Content-Type.
401	Check the access ID, signature and server clock.
403	Check credential scopes, account permissions and allowed source IPs.
404	Check the endpoint and VPS reference.
409	Read error.code: the VPS state, an existing action or a reused nonce may conflict with the request.
422	Correct the fields named in the error.
426	Use HTTPS.
429	Wait for Retry-After before sending another request.
5xx	An API or upstream error occurred. Keep the request ID and check the outcome before repeating a write.

Rate limits

The default limit is 120 requests per minute per API credential. X-RateLimit-Limit and X-RateLimit-Remaining show your allowance. A 429 response includes Retry-After in seconds.

For larger accounts, use POST /v1/vps/query to read up to 100 VPS records at once. Space out background requests and reuse cached resource readings.

Timeouts and retries

A timeout does not tell you whether an action completed. Check the VPS or reinstall operation first. For orders and reinstalls, retain the original action key and body. Create fresh authentication headers for every request.