API Reference

Otwa Cloud API

The Otwa Cloud REST API lets you deploy servers, manage power states, retrieve SSH/RDP credentials, and automate your infrastructure programmatically. All responses are JSON.

Base URL
https://otwa.cloud/api/v1
Format
JSON
Auth
Bearer API Key
OpenAPI JSON Markdown llms.txt
WHMCS Module
Drop-in provisioning for WHMCS 8+
Auto-deploy Otwa Cloud VPS from WHMCS orders. Lifecycle hooks, SSO button, live stats. Install guide →
Reseller Program
Wholesale rates with auto-tiering
Resell Otwa Cloud under your own brand. Starts at 10% off, scales to 25%. Learn more →

Authentication

Every request must include your API key in the Authorization header. Generate and manage keys from your dashboard API page.

shell
$ curl https://otwa.cloud/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Scopes

Each key carries one or more scopes. Calls missing a required scope return 403. servers:destroy is opt-in and NOT included in the default set — mint a dedicated key for destructive integrations.

account:readAccount profile, balance, reseller state, plans, regions, OS list
servers:readList, view servers, credentials, live stats, add-on catalog
servers:writeDeploy, rename, power, reset password, purchase add-ons, issue SSO
servers:destroyPermanently terminate a server (opt-in — not in defaults)
billing:readView balance and invoice history

Error Codes

All errors return a JSON body with a message field.

400

Bad Request

Missing or invalid request body parameters.

401

Unauthorized

Missing, invalid, or expired API key.

402

Payment Required

Insufficient wallet balance to deploy a server.

403

Forbidden

API key lacks the required permission for this action.

404

Not Found

The requested resource does not exist or belongs to another account.

429

Too Many Requests

Rate limit exceeded (100 req/min). Retry after X-RateLimit-Reset.

500

Internal Server Error

Unexpected server error. If persistent, contact support.

Account

3 endpoints

Catalog

3 endpoints

Servers

15 endpoints

Server Statuses

The status field on server objects transitions through these values. Poll GET /api/v1/servers/:id to track provisioning.

pending

Order placed, waiting for worker to pick up the provision job.

building

VM is being deployed, configured, and booted. Takes ~60–120s.

running

Server is online and accepting connections.

stopped

Server is powered off. Can be started via power API.

suspended

Account billing issue — server inaccessible. Add funds to reactivate.

failed

Provisioning failed. Contact support or use admin retry.

terminated

Permanently destroyed. All data and IPs released.

Typical flow: pending → building → running (~60–120s from order)

Rate Limits

The API is limited to 100 requests per minute per API key. Requests exceeding this limit return 429 Too Many Requests. The response headers include X-RateLimit-Remaining and X-RateLimit-Reset.

Machine Readable

These endpoints serve the API reference in formats designed for automated tooling — LLMs, code generators, and API clients.

OpenAPI 3.0.3

Full spec for Swagger UI, Postman, code generators

/openapi.json
Markdown Docs

Plain-text reference easy for LLMs to read and index

/docs.md
llms.txt

Standard AI-crawler index listing key resources

/llms.txt

Changelog

All notable API changes. Versioning follows semantic conventions — minor versions add features, patch versions fix bugs.

v1.9latest2026-04-24
  • newPOST /servers/:id/reinstall — wipe the disk and rebuild from a new OS template while preserving server ID, label, region, primary IPv4, and attached add-ons. Billing is unchanged. Requires the elevated `servers:destroy` scope because all data on the disk is lost, same blast radius as termination. Accepts an optional `Idempotency-Key` header for 24 h replay safety.
  • improvedScope description for `servers:destroy` now says "terminate or reinstall" to reflect the reinstall action added here. Grant sparingly.
v1.82026-04-21
  • newNew scope `servers:destroy`, required for DELETE /servers/:id. Separated from `servers:write` so a leaked deploy/automation key cannot nuke infrastructure. NOT included in the default scope set — opt in explicitly when minting a key for a destructive integration. Existing keys were grandfathered via `*`.
  • improvedAPI-key scopes are now enforced at the guard layer. Previously the `permissions` column was display-only and any key could call any /v1 endpoint. Calls missing a required scope now return 403.
  • improvedGET /products, /regions, /os-templates now correctly require the `account:read` scope. They were documented as public but the backend always required an API key — docs are now aligned with reality.
v1.72026-04-19
  • newGET /regions — flat list of every deployment region currently offered, with a display-ready name. Keeps your region pickers in sync without hardcoded slugs.
  • newGET /os-templates — every live operating system available at deploy time, flattened per version. The returned id is the exact value to pass as os on POST /servers.
  • newGET /reseller — reseller state of the authenticated account: partner status, brand slug, brand name, and margin percent. Companion to the web /me/reseller endpoint for API-key integrations.
  • newPOST /sso and POST /servers/:id/sso — mint a 5-minute single-use login URL that signs the user straight into the dashboard (or a specific server detail page). Useful for embedding Otwa Cloud inside a billing portal, helpdesk, or WHMCS client area.
  • newPOST /servers/:id/password-reset — rotates the root or Administrator password on a running server and returns the new credential. Applied live through the guest agent, no reboot required.
  • newUbuntu 22.04 LTS and Rocky Linux 10.1 templates are now available at deploy time.
  • improvedPOST /servers now honours an Idempotency-Key header. Retrying the same request with the same key within 24 hours returns the cached result instead of creating a duplicate server — safe for WHMCS and other auto-retry clients.
  • improvedThe os slug format in POST /servers examples has been updated to use a dot between family and version (ubuntu-24.04, rocky-10.1) so that it matches what GET /servers, GET /servers/:id, and GET /os-templates return. Old dotless slugs (ubuntu-2404) still work but will be removed in a future major version.
v1.62026-04-18
  • newGET /public/affiliates/rule — unauthenticated endpoint that exposes the live affiliate program rule: enabled, trigger (verified_signup | first_deposit | every_deposit), rewardType (fixed | percent), and rewardAmount. Lets integrators surface the current offer without duplicating it in their own copy.
  • improvedDELETE /servers/:id — clarified that API-key callers destroy the server immediately. The web dashboard now requires a 6-digit email code or TOTP confirmation, but the API key path intentionally bypasses that step since the key itself is the proof of intent.
  • fixedPOST /servers — body example and description now match the real CreateServerDto. productId, os, and osTemplate are required; label and hostname are optional (auto-generated if omitted); addons take the hash-style IDs returned by GET /servers/:id/addons.
v1.52026-04-17
  • newGET /servers/:id/addons — see every add-on offered by your server's plan, the prorated price to attach it today, and whether the add-on type is already active.
  • newPOST /servers/:id/addons — attach an add-on to a running server. Prorated price is charged to your wallet immediately; the full monthly price is included in future renewals. Guest-OS network configuration for new IPs is your responsibility.
  • newAlmaLinux 10.1 and Windows 11 Pro templates are now available at deploy time.
  • improvedOnly one add-on per type (extra-ip, ip-class, backup) can be active on a server. Orders that include duplicates are rejected with 400.
v1.42026-04-14
  • newGET /servers/:id/stats — live VM metrics: CPU%, memory used/total, disk read/write KB/s, network RX/TX KB/s.
  • newWindows Server 2025 & 2022 support. GET /servers/:id/credentials now returns rdpAddress and Administrator username for Windows VMs.
  • newIP class block add-ons (/25). Additional IPs returned in networking.additionalIps on GET /servers/:id and GET /servers.
  • improvedPOST /servers — hostname and label are now required fields (previously optional).
v1.32026-04-12
  • improvedAll write endpoints now reject requests from keys without the required permission scope (403 instead of silent ignore).
v1.22026-04-03
  • newAuto-provisioning pipeline: VM deployed, network configured, disk resized, OS booted, credentials set — all in ~60–120 seconds.
  • newActivity logging: login, deploy, power actions, reinstall, delete, 2FA changes all recorded.
  • newOrder confirmation and "Server Ready" email notifications.
  • newBilling automation: renewal cron, suspension on payment failure, auto-termination after grace period (configurable in SuperAdmin).
v1.12026-04-02
  • newIP pool management: allocate, release, and track individual IPs with gateway/netmask/CIDR metadata.
  • newCoupon system: create and redeem promotional codes at checkout.
  • improvedGET /servers now includes additionalIps array from IP pool.
v1.02026-04-01
  • newInitial API release: account info, product listing, server CRUD, credentials, power actions, live stats.

Ready to automate?

Create a free account to generate your first API key and start deploying.

Get Started Free