API Reference - Servosphere LLC

Introduction

The Servosphere API is a RESTful interface that provides programmatic access to manage your infrastructure resources. All API requests should be made over HTTPS to api.servosphere.net/v2

Base URL

https://api.servosphere.net/v2

Authentication

All API requests require authentication using an API key. You can generate API keys from your account dashboard.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://api.servosphere.net/v2/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Rate Limits

API requests are limited to ensure fair usage and system stability.

1000 Requests per hour for standard endpoints

100 Requests per hour for resource-intensive operations

429 Too Many Requests - Rate limit exceeded

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Handling

Understanding error responses and how to handle them properly in your applications.

Error Response Format

All API errors follow a consistent JSON format with error codes and descriptive messages.

Error Response Structure

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested server could not be found",
    "details": {
      "resource_type": "server",
      "resource_id": "srv_invalid123"
    },
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abcd1234"
  }
}

Common Error Codes

400 Bad Request - Invalid request format or parameters

401 Unauthorized - Invalid or missing API key

403 Forbidden - Insufficient permissions

404 Not Found - Resource does not exist

409 Conflict - Resource already exists or conflict

422 Unprocessable Entity - Validation errors

429 Too Many Requests - Rate limit exceeded

500 Internal Server Error - Unexpected server error

503 Service Unavailable - Temporary service interruption

Servers

Manage your server infrastructure including creation, configuration, and monitoring.

GET /servers List all servers

Returns a paginated list of all servers in your account.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
status	string	Filter by status: active, inactive, suspended

Response

Response Body

{
  "data": [
    {
      "id": "srv_1234567890",
      "name": "web-server-01",
      "status": "active",
      "ip_address": "185.123.45.67",
      "location": "Amsterdam",
      "specs": {
        "cpu": 4,
        "ram": 8192,
        "disk": 160,
        "bandwidth": 10000
      },
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "pages": 3
  }
}

Error Response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

POST /servers Create a new server

Provision a new server with specified configuration.

Request Body

Field	Type	Description
name required	string	Server hostname
plan required	string	Plan ID (e.g., "vps-medium")
location required	string	Data center location: "AMS" or "IST"
os	string	Operating system (default: "ubuntu-22.04")

Example Request

{
  "name": "api-server-01",
  "plan": "vps-medium",
  "location": "AMS",
  "os": "ubuntu-22.04",
  "ssh_keys": ["ssh-rsa AAAAB3..."]
}

DELETE /servers/{server_id} Delete a server

Permanently delete a server and all associated data.

Warning

This action is irreversible. All data will be permanently deleted.

Networks

Manage virtual networks, VLANs, and network configurations for your infrastructure.

GET /networks List all networks

Returns a list of all networks configured in your account.

Response

Response Body

{
  "data": [
    {
      "id": "net_1234567890",
      "name": "production-network",
      "cidr": "10.0.0.0/24",
      "vlan_id": 100,
      "location": "AMS",
      "status": "active",
      "gateway": "10.0.0.1",
      "dns_servers": ["8.8.8.8", "8.8.4.4"],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST /networks Create a new network

Create a new virtual network with specified configuration.

Request Body

Field	Type	Description
name required	string	Network name identifier
cidr required	string	CIDR notation (e.g., "10.0.0.0/24")
vlan_id	integer	VLAN ID (1-4094)

PUT /networks/{network_id} Update network configuration

Update network settings including DNS servers and gateway configuration.

Storage

Manage block storage volumes, snapshots, and storage configurations.

GET /storage/volumes List storage volumes

Returns a list of all storage volumes in your account.

Response

Response Body

{
  "data": [
    {
      "id": "vol_1234567890",
      "name": "database-storage",
      "size_gb": 500,
      "type": "ssd",
      "status": "attached",
      "server_id": "srv_1234567890",
      "mount_point": "/dev/sdb",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST /storage/volumes Create storage volume

Create a new block storage volume.

Request Body

Field	Type	Description
name required	string	Volume name
size_gb required	integer	Size in GB (min: 10, max: 10000)
type required	string	Storage type: "ssd" or "hdd"

POST /storage/volumes/{volume_id}/attach Attach volume to server

Attach a storage volume to a server instance.

Request Body

Field	Type	Description
server_id required	string	Target server ID

POST /storage/snapshots Create volume snapshot

Create a point-in-time snapshot of a storage volume.

Monitoring

Access real-time metrics, alerts, and monitoring data for your infrastructure.

GET /monitoring/servers/{server_id}/metrics Get server metrics

Retrieve real-time and historical metrics for a specific server.

Query Parameters

Parameter	Type	Description
period	string	Time period: "1h", "24h", "7d", "30d"
metrics	string	Comma-separated metrics: cpu,memory,disk,network

Response

Response Body

{
  "server_id": "srv_1234567890",
  "period": "1h",
  "metrics": {
    "cpu": {
      "usage_percent": 45.2,
      "history": [
        {"timestamp": "2025-01-15T10:00:00Z", "value": 43.1},
        {"timestamp": "2025-01-15T10:05:00Z", "value": 45.2}
      ]
    },
    "memory": {
      "usage_percent": 67.8,
      "total_mb": 8192,
      "used_mb": 5551
    },
    "disk": {
      "usage_percent": 32.1,
      "total_gb": 160,
      "used_gb": 51
    },
    "network": {
      "in_mbps": 12.4,
      "out_mbps": 8.7
    }
  }
}

GET /monitoring/alerts List active alerts

Get all active alerts and notifications for your infrastructure.

POST /monitoring/alerts Create alert rule

Create a new monitoring alert rule with specified conditions.

Request Body

Field	Type	Description
name required	string	Alert rule name
metric required	string	Metric to monitor: cpu, memory, disk, network
threshold required	number	Alert threshold value
condition required	string	Condition: "greater_than", "less_than"

Firewall

Manage firewall rules, security groups, and network access control policies.

GET /firewall/rules List firewall rules

Returns all firewall rules configured for your servers.

Response

Response Body

{
  "data": [
    {
      "id": "fw_1234567890",
      "name": "allow-http",
      "protocol": "tcp",
      "port_range": "80",
      "source": "0.0.0.0/0",
      "action": "allow",
      "priority": 100,
      "server_id": "srv_1234567890",
      "enabled": true,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST /firewall/rules Create firewall rule

Create a new firewall rule to control network access.

Request Body

Field	Type	Description
name required	string	Rule name
protocol required	string	Protocol: tcp, udp, icmp
port_range required	string	Port or range (e.g., "80", "8080-8090")
source required	string	Source IP/CIDR (e.g., "0.0.0.0/0")
action required	string	Action: "allow" or "deny"

PUT /firewall/rules/{rule_id} Update firewall rule

Modify an existing firewall rule configuration.

DELETE /firewall/rules/{rule_id} Delete firewall rule

Remove a firewall rule from the system.

Backups

Manage automated backups, snapshots, and data recovery operations.

GET /backups List all backups

Returns a list of all backups and snapshots in your account.

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server ID
type	string	Filter by type: "manual", "automatic"

Response

Response Body

{
  "data": [
    {
      "id": "bkp_1234567890",
      "name": "web-server-daily-backup",
      "server_id": "srv_1234567890",
      "type": "automatic",
      "status": "completed",
      "size_gb": 85.4,
      "created_at": "2025-01-15T02:00:00Z",
      "retention_days": 30
    }
  ]
}

POST /backups Create manual backup

Create an immediate backup of a server or volume.

Request Body

Field	Type	Description
name required	string	Backup name
server_id required	string	Server to backup
retention_days	integer	Retention period (default: 30)

POST /backups/{backup_id}/restore Restore from backup

Restore a server from a backup snapshot.

Warning

Restore operations will overwrite existing data. Ensure you have a recent backup before proceeding.

POST /backups/schedules Configure backup schedule

Set up automated backup schedules for your servers.

Billing

Access billing information, usage statistics, and payment management.

GET /billing/usage Get current usage

Retrieve current billing period usage and costs.

Query Parameters

Parameter	Type	Description
period	string	Billing period: "current", "previous"

Response

Response Body

{
  "period": "2025-01",
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-31T23:59:59Z",
  "currency": "USD",
  "total_cost": 156.78,
  "breakdown": {
    "servers": {
      "count": 3,
      "cost": 120.00
    },
    "storage": {
      "gb_hours": 24000,
      "cost": 24.00
    },
    "bandwidth": {
      "gb_transferred": 1250,
      "cost": 12.50
    },
    "backups": {
      "gb_stored": 300,
      "cost": 0.28
    }
  }
}

GET /billing/invoices List invoices

Returns a list of all invoices for your account.

Response

Response Body

{
  "data": [
    {
      "id": "inv_1234567890",
      "number": "INV-2025-001",
      "status": "paid",
      "amount": 156.78,
      "currency": "USD",
      "period": "2025-01",
      "due_date": "2025-02-01T00:00:00Z",
      "paid_at": "2025-01-28T14:30:00Z",
      "download_url": "https://api.servosphere.net/v2/billing/invoices/inv_1234567890/pdf"
    }
  ]
}

GET /billing/invoices/{invoice_id} Get invoice details

Retrieve detailed information for a specific invoice.

GET /billing/payment-methods List payment methods

Returns all configured payment methods for your account.

Servosphere API Reference

Introduction

Authentication

Rate Limits

Error Handling

Common Error Codes

Servers

Query Parameters

Response

Request Body

Networks

Response

Request Body

Storage

Response

Request Body

Request Body

Monitoring

Query Parameters

Response

Request Body

Firewall

Response

Request Body

Backups

Query Parameters

Response

Request Body

Billing

Query Parameters

Response

Response