📡 API v1 Reference

Programmatically manage your Hostingowy VPS instances — provision servers, query status, and automate your infrastructure.

The Hostingowy API follows RESTful conventions. All requests must be authenticated using a scoped API key. Responses are always JSON with a consistent envelope:

{
  "success": true,
  "data": { /* response payload */ },
  "meta": { /* pagination, filters, etc. */ }
}

Error responses use the same envelope with success: false and an error field:

{
  "success": false,
  "error": "Description of what went wrong",
  "docs": "https://hostingowy.com/docs/api"
}

Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header.

curl -H "Authorization: Bearer hkey_your_api_key_here" \
  https://hostingowy.com/api/v1/me

Getting an API Key

Generate API keys from your customer dashboard. Each key can be given a label and scoped to specific permissions.

Scopes

API keys are scoped to limit what they can do. Available scopes:

You can manage (create, list, revoke) your API keys programmatically via the key management API.

Rate Limiting

API requests are rate-limited per API key to ensure fair usage for all customers.

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests:

{
  "success": false,
  "error": "Rate limit exceeded. Max 1000 requests/hour per API key.",
  "retryAfter": "1 hour"
}

You can check your current usage via the GET /api/v1/me endpoint, which includes rate limit counters. If you need higher limits, contact support.

Error Codes

Endpoints

{
  "success": true,
  "data": {
    "keyId": "a73c73ab-187f-49c6-9117-defaafad3738",
    "label": "My CLI Tool",
    "scopes": ["servers:read", "servers:write"],
    "createdAt": "2026-07-20T15:20:47.778Z",
    "lastUsedAt": "2026-07-20T15:30:00.000Z",
    "rateLimit": {
      "used": 42,
      "limit": 1000,
      "windowResetAt": "2026-07-20T16:20:47.778Z"
    }
  }
}

curl -H "Authorization: Bearer hkey_your_api_key" \
  https://hostingowy.com/api/v1/me

Node.js SDK

The official Hostingowy Node.js SDK makes it easy to integrate with the API. Install it from GitHub:

npm install hostingowy-api

⬇ Download Node.js SDK (.tgz)

Quick Start

const Hostingowy = require('hostingowy-api');

// Initialize with your API key
const hostingowy = new Hostingowy({
  apiKey: 'hkey_your_api_key_here'
});

// List your servers
async function listServers() {
  const servers = await hostingowy.servers.list();
  console.log(servers);
}

// Create a new VPS
async function createServer() {
  const server = await hostingowy.servers.create({
    plan: 'vps-2',
    region: 'lon1',
    os: 'ubuntu-22.04',
    hostname: 'my-app-server'
  });
  console.log(`Server ${server.id} is being provisioned`);
}

// Get server details
async function getServer(serverId) {
  const server = await hostingowy.servers.get(serverId);
  console.log(`Status: ${server.status}, IP: ${server.ipv4}`);
}

// Check API key info
async function getMe() {
  const me = await hostingowy.me();
  console.log(`Key: ${me.label}, Used: ${me.rateLimit.used}/${me.rateLimit.limit}`);
}

Installation

The SDK source is available at github.com/hostingowy/api-sdk-node. To install directly from GitHub:

npm install git+https://github.com/hostingowy/api-sdk-node.git

API Reference

Python SDK

The official Hostingowy Python SDK is available on PyPI. Install it directly:

pip install hostingowy

📦 View on PyPI 🐙 GitHub

Quick Start

from hostingowy import Hostingowy
import os

# Initialize with your API key
client = Hostingowy(api_key=os.environ['HOSTINGOWY_API_KEY'])

# List your servers
servers = client.servers.list()
print(f'Found {len(servers["data"])} server(s)')

# Create a new VPS
server = client.servers.create(
    plan='vps-1',
    region='lon1',
    os='ubuntu-22.04',
    hostname='my-python-server'
)
print(f'Server provisioning: {server["data"]["id"]}')

# Get server details
detail = client.servers.get(server['data']['id'])
print(f'Status: {detail["data"]["status"]}')

# Check API key info
me = client.me()
print(f'Key: {me["data"]["label"]}')

You can also use the API directly with requests:

import requests

API_BASE = "https://hostingowy.com/api/v1"
API_KEY = "hkey_your_api_key_here"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# List servers
response = requests.get(f"{API_BASE}/servers", headers=headers)
servers = response.json()
print(f"Found {servers['meta']['total']} server(s)")

# Create a server
new_server = {
    "plan": "vps-1",
    "region": "lon1",
    "os": "ubuntu-22.04",
    "hostname": "my-python-server"
}
response = requests.post(f"{API_BASE}/servers", json=new_server, headers=headers)
result = response.json()
print(f"Server provisioning: {result['data']['id']}")

# Get server details
server_id = result['data']['id']
response = requests.get(f"{API_BASE}/servers/{server_id}", headers=headers)
server = response.json()
print(f"Status: {server['data']['status']}")

# Check API key info
response = requests.get(f"{API_BASE}/me", headers=headers)
me = response.json()
print(f"Key: {me['data']['label']}, Usage: {me['data']['rateLimit']['used']}/{me['data']['rateLimit']['limit']}")

cURL Examples

All API endpoints can be used directly with cURL. Here's a complete workflow:

#!/bin/bash
API_KEY="hkey_your_api_key"
BASE="https://hostingowy.com/api/v1"

# 1. Check your API key info
curl -s -H "Authorization: Bearer $API_KEY" "$BASE/me" | jq .

# 2. List your servers
curl -s -H "Authorization: Bearer $API_KEY" "$BASE/servers" | jq .

# 3. Create a VPS ("lon1" = London, "vps-1" = 1 vCPU, 1GB RAM)
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"vps-1","region":"lon1","os":"ubuntu-22.04"}' \
  "$BASE/servers" | jq .

# 4. Get server details (replace SERVER_ID)
curl -s -H "Authorization: Bearer $API_KEY" \
  "$BASE/servers/SERVER_ID" | jq .

# 5. Destroy a server (replace SERVER_ID)
curl -s -X DELETE \
  -H "Authorization: Bearer $API_KEY" \
  "$BASE/servers/SERVER_ID" | jq .

# 6. Filter servers by status
curl -s -H "Authorization: Bearer $API_KEY" \
  "$BASE/servers?status=active" | jq .

API Key Management

You can manage your API keys programmatically using these internal endpoints:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"customerId":"your-customer-id","label":"My CI Key","scopes":["servers:read","servers:write"]}' \
  https://hostingowy.com/api/keys

curl "https://hostingowy.com/api/keys?customerId=your-customer-id"

curl -X DELETE "https://hostingowy.com/api/keys/key-id?customerId=your-customer-id"

Plan Reference

Region Reference

All datacentres feature 24/7 security, redundant power (N+1), and multiple Tier-1 upstream providers.

OS Images