API Reference

Introduction

The SparrowHost API is a REST API that gives you full programmatic control over your cloud infrastructure. Every action available in the dashboard — deploying servers, starting and stopping instances, viewing invoices — is available through the API.

All requests are made over HTTPS to https://api.sparrowhost.net. Requests and responses use JSON. All monetary values are in Indian Rupees (₹ / INR).

Authentication

The API uses Bearer token authentication. Pass your API key in the Authorization header with every request.

Authorization: Bearer sph_your_api_key_here

Getting an API key

API keys are generated from the SparrowHost dashboard:

1. Log in to your SparrowHost dashboard.
2. Navigate to Account → API Keys.
3. Click + Create API Key.
4. Give your key a name, select the required scopes, and optionally set an IP allowlist or expiry date.
5. Copy the key — it is shown only once. Store it securely (e.g., an environment variable).

Key format

API keys always start with the prefix sph_ followed by 48 hex characters (192 bits of entropy). Example:

sph_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6

IP allowlisting

When creating a key you can restrict it to specific IPv4 or IPv6 addresses. Requests arriving from unlisted IPs will be rejected with a 403 Forbidden response.

Key expiry

Keys can have an optional expiry date. Expired keys return 401 Unauthorized. You can also revoke a key at any time from the dashboard.

Scopes

Every API key has one or more scopes that determine what actions it can perform. Select only the scopes your use-case needs (principle of least privilege).

Rate Limits

The API enforces rate limits per API key to ensure fair usage.

When you exceed the rate limit, the API returns 429 Too Many Requests. Back off exponentially and retry.

Responses & Errors

Success envelope

All successful responses are wrapped in a standard envelope:

{
  "success": true,
  "data": { ... }
}

Error envelope

{
  "success": false,
  "message": "Human-readable error description"
}

HTTP status codes

Account

Returns the authenticated account's profile and current balance. No scope required.

Response

{
  "success": true,
  "data": {
    "id": "clxyz123",
    "name": "Anant Pandey",
    "email": "anant@sparrowhost.in",
    "balance": "2500.00",
    "currency": "INR",
    "kycVerified": true
  }
}

List Servers

Returns all VPS servers belonging to the authenticated account. Requires the vps:read scope.

Response

{
  "success": true,
  "data": [
    {
      "id": "clserver123",
      "name": "test.com",
      "status": "running",
      "ipv4": "192.0.2.10",
      "ipv6": null,
      "region": "in-noida-1",
      "plan": "vps-amd-2vcpu-4gb",
      "os": "Ubuntu 24.04 LTS",
      "cpuCores": 2,
      "ramMb": 4096,
      "diskGb": 80,
      "bandwidthGb": 2000,
      "monthlyPrice": "850.00",
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Get Server

Returns details for a single server. Requires vps:read.

Path parameters

Response

Same shape as a single item from the list endpoint above.

Deploy Server

Provisions a new VPS server. Requires the vps:deploy scope. Your account balance must be at least ₹1,000 before this call will succeed.

Request body

{
  "name": "web-01",
  "productId": "vps-amd-2vcpu-4gb",
  "regionId": "in-noida-1",
  "osId": "ubuntu-24-04"
}

Response

{
  "success": true,
  "data": {
    "id": "clserver456",
    "name": "web-01",
    "status": "provisioning",
    "ipv4": null,
    "region": "in-noida-1",
    "plan": "vps-amd-2vcpu-4gb",
    "createdAt": "2026-05-08T12:00:00.000Z"
  }
}

Server Actions

Perform a power or lifecycle action on a server. Requires vps:write.

Path parameters

Request body

{ "action": "reboot" }

Actions reference

Response

{
  "success": true,
  "data": { "message": "reboot initiated" }
}

Rename Server

Update the display name / hostname label of a server. Requires vps:write.

Request body

{ "name": "api-server-prod" }

Response

{
  "success": true,
  "data": { "id": "clserver123", "name": "api-server-prod" }
}

Delete Server

Permanently terminates and deletes a server and all its data. This action is irreversible. Requires vps:delete.

Response

{
  "success": true,
  "data": { "message": "Server deleted successfully" }
}

Examples

Check your balance (curl)

curl -s \
  -H "Authorization: Bearer sph_your_key_here" \
  https://api.sparrowhost.net/api/v1/account | jq .data.balance

List all servers

curl -s \
  -H "Authorization: Bearer sph_your_key_here" \
  https://api.sparrowhost.net/api/v1/servers | jq .

Reboot a server

curl -s -X POST \
  -H "Authorization: Bearer sph_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}' \
  https://api.sparrowhost.net/api/v1/servers/clserver123/actions

Deploy a new server

curl -s -X POST \
  -H "Authorization: Bearer sph_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-01",
    "productId": "vps-amd-2vcpu-4gb",
    "regionId": "in-noida-1",
    "osId": "ubuntu-24-04"
  }' \
  https://api.sparrowhost.net/api/v1/servers

Node.js example

const API_KEY = process.env.SPARROWHOST_API_KEY;
const BASE    = "https://api.sparrowhost.net";

async function listServers() {
  const res = await fetch(`${BASE}/api/v1/servers`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const { data } = await res.json();
  return data; // array of servers
}

async function rebootServer(id) {
  const res = await fetch(`${BASE}/api/v1/servers/${id}/actions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ action: "reboot" }),
  });
  return res.json();
}

listServers().then(console.log);

Python example

import os, requests

API_KEY = os.environ["SPARROWHOST_API_KEY"]
BASE    = "https://api.sparrowhost.net"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# List servers
servers = requests.get(f"{BASE}/api/v1/servers", headers=HEADERS).json()["data"]

# Reboot first server
server_id = servers[0]["id"]
requests.post(
    f"{BASE}/api/v1/servers/{server_id}/actions",
    headers=HEADERS,
    json={"action": "reboot"},
)

Changelog