API Documentation

Introduction

The Hostraha Cloud API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Hostraha Cloud API to programmatically manage all aspects of your infrastructure, from creating and managing virtual servers to configuring networking and handling DNS records.

Example Request

curl -X GET https://api.hostraha.com/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentication

The Hostraha API uses API keys to authenticate requests. You can view and manage your API keys in the Hostraha dashboard.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Security Note: Authentication should be handled via Authorization header with a Bearer token, not via query parameters.

Authentication Example

// Correct way to authenticate API requests
fetch('https://api.hostraha.com/v1/servers', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})

// INCORRECT - Never do this
// fetch('https://api.hostraha.com/v1/servers?api_key=YOUR_API_KEY')

API Key Types

Hostraha offers two types of API keys:

Key Type	Access Level	Use Case
Secret Key	Full account access	Server-side applications
Restricted Key	Limited by scope & IP	Client applications with specific permissions

Rate Limits

The Hostraha API implements rate limiting to prevent abuse and ensure the stability of our service. Rate limits are applied on a per-API key basis and reset every hour.

Plan	Rate Limit	Reset Period
Standard	60 requests per minute	60 seconds
Professional	120 requests per minute	60 seconds
Enterprise	300 requests per minute	60 seconds

If you exceed the rate limit, a 429 Too Many Requests error is returned. The response headers include information about the current rate limit status:

X-RateLimit-Limit: The maximum number of requests allowed in the current period
X-RateLimit-Remaining: The number of remaining requests in the current period
X-RateLimit-Reset: The timestamp when the rate limit will reset

Rate Limit Response Example

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1617203462
Content-Type: application/json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again after 45 seconds.",
    "documentation_url": "https://docs.hostraha.com/api/rate-limits"
  }
}

Error Handling

The Hostraha API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with our servers.

Error Code	Meaning
400 Bad Request	The request was unacceptable, often due to missing a required parameter.
401 Unauthorized	No valid API key provided.
403 Forbidden	The API key doesn't have permissions to perform the request.
404 Not Found	The requested resource doesn't exist.
429 Too Many Requests	Too many requests hit the API too quickly.
500, 502, 503, 504 Server Errors	Something went wrong on our end.

Error Response Example

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested server with ID 'srv-123456' could not be found.",
    "documentation_url": "https://docs.hostraha.com/api/errors#resource_not_found"
  }
}

Error Handling Best Practices

When handling errors from the API, we recommend the following best practices:

Always check the HTTP status code first
Parse the error code in the response body to handle specific error conditions
Implement exponential backoff for retrying failed requests
Log the full error response for debugging

Note: For sensitive operations, implement idempotency by including a client-generated request ID. This prevents duplicate operations if a request is retried due to network issues.

Servers

The servers endpoint allows you to create, manage, and delete virtual private servers within your account.

GET

/v1/servers

List all servers

Request

curl -X GET https://api.hostraha.com/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "servers": [
    {
      "id": "srv-123456",
      "name": "web-server-1",
      "status": "running",
      "region": "us-east",
      "size": "standard-2vcpu-4gb",
      "memory": 4096,
      "vcpus": 2,
      "disk": 80,
      "created_at": "2025-03-15T19:22:16Z",
      "ip_addresses": {
        "v4": [
          {
            "ip": "142.93.18.211",
            "type": "public"
          },
          {
            "ip": "10.128.0.5",
            "type": "private"
          }
        ],
        "v6": [
          {
            "ip": "2604:a880:400:d1::8c:6001",
            "type": "public"
          }
        ]
      }
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 25,
    "page": 1
  }
}

POST

/v1/servers

Create a new server

Request

curl -X POST https://api.hostraha.com/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-2",
    "region": "us-east",
    "size": "standard-2vcpu-4gb",
    "image": "ubuntu-22-04",
    "ssh_keys": [
      "ssh-abcdef123456"
    ],
    "backups": true,
    "vpc_id": "vpc-123456"
  }'

Server Management

GET

/v1/servers/{server_id}

Retrieve a specific server

PUT

/v1/servers/{server_id}

Update server details

DELETE

/v1/servers/{server_id}

Delete a server

POST

/v1/servers/{server_id}/actions

Perform an action on a server (reboot, power off, etc.)

Security Note: Deleting a server is permanent and cannot be undone. Always confirm before executing this operation.

SSH Keys

SSH keys allow secure access to your servers without using passwords. You can manage your SSH keys through the API.

GET

/v1/ssh-keys

List all SSH keys

POST

/v1/ssh-keys

Create a new SSH key

Adding an SSH Key

curl -X POST https://api.hostraha.com/v1/ssh-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Laptop",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDXYZ..."
  }'

Python SDK

Our official Python SDK makes it easy to integrate with the Hostraha API in your Python applications.

Installation

pip install

pip install hostraha

Usage Example

Python Example

import hostraha

# Initialize the client
client = hostraha.Client(api_key='YOUR_API_KEY')

# List all servers
servers = client.servers.list()

# Create a new server
new_server = client.servers.create(
    name='web-server-3',
    region='us-east',
    size='standard-2vcpu-4gb',
    image='ubuntu-22-04',
    ssh_keys=['ssh-abcdef123456']
)

# Get a specific server
server = client.servers.get('srv-123456')

# Delete a server
client.servers.delete('srv-123456')

Best Practice: Store your API key in environment variables or a secure configuration file, not directly in your code.

JavaScript SDK

Our JavaScript SDK is available for both Node.js and browser environments.

Installation

npm install

npm install hostraha-js

Node.js Example

JavaScript Example

const Hostraha = require('hostraha-js');

// Initialize the client
const hostraha = new Hostraha({
  apiKey: process.env.LINESERVE_API_KEY
});

// Example: List all servers
async function listServers() {
  try {
    const { servers } = await hostraha.servers.list();
    console.log(`Found ${servers.length} servers`);
    return servers;
  } catch (error) {
    console.error('Error listing servers:', error);
  }
}

listServers();

Introduction

Authentication

API Key Types

Rate Limits

Error Handling

Error Handling Best Practices

Servers

Server Management

SSH Keys

Python SDK

Installation

Usage Example

JavaScript SDK

Installation

Node.js Example

Ready to Automate Your Infrastructure?