Compute API

The Lineserve Compute API allows you to programmatically manage virtual private servers (VPS), dedicated servers, and Kubernetes clusters.

Base URL

https://api.lineserve.com/v1

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

VPS Management

List VPS Instances

Get a list of all VPS instances in your account.

Endpoint: GET /vps

Parameters:

region (optional): Filter by region
status (optional): Filter by status (running, stopped, creating, etc.)
page (optional): Page number for pagination
per_page (optional): Number of results per page (max 100)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/vps?region=nairobi&status=running"

Example Response:

{
  "vps_instances": [
    {
      "id": "vps_123456",
      "name": "web-server-prod",
      "status": "running",
      "region": "nairobi",
      "image": "ubuntu-22.04",
      "size": "starter",
      "vcpus": 1,
      "memory": 1024,
      "disk": 25,
      "ip_address": "192.168.1.100",
      "private_ip": "10.0.1.100",
      "created_at": "2024-01-15T10:30:00Z",
      "tags": ["production", "web"]
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 25,
    "pages": 1
  }
}

Create VPS Instance

Create a new VPS instance.

Endpoint: POST /vps

Parameters:

name (required): Instance name
region (required): Deployment region
image (required): Operating system image
size (required): Instance size
ssh_keys (optional): Array of SSH key IDs
private_networking (optional): Enable private networking
backups (optional): Enable automatic backups
monitoring (optional): Enable enhanced monitoring
user_data (optional): Cloud-init script
tags (optional): Array of tags

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-web-server",
    "region": "nairobi",
    "image": "ubuntu-22.04",
    "size": "starter",
    "ssh_keys": ["ssh_key_123"],
    "private_networking": true,
    "backups": true,
    "tags": ["web", "production"]
  }' \
  https://api.lineserve.com/v1/vps

Example Response:

{
  "vps": {
    "id": "vps_789012",
    "name": "my-web-server",
    "status": "creating",
    "region": "nairobi",
    "image": "ubuntu-22.04",
    "size": "starter",
    "vcpus": 1,
    "memory": 1024,
    "disk": 25,
    "ip_address": null,
    "private_ip": null,
    "created_at": "2024-01-15T11:00:00Z",
    "tags": ["web", "production"]
  }
}

Get VPS Instance

Retrieve details of a specific VPS instance.

Endpoint: GET /vps/{vps_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/vps/vps_123456

Update VPS Instance

Update VPS instance properties.

Endpoint: PUT /vps/{vps_id}

Parameters:

name (optional): New instance name
tags (optional): Update tags

Example Request:

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-web-server",
    "tags": ["web", "production", "updated"]
  }' \
  https://api.lineserve.com/v1/vps/vps_123456

Delete VPS Instance

Delete a VPS instance permanently.

Endpoint: DELETE /vps/{vps_id}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/vps/vps_123456

VPS Actions

Start VPS

Start a stopped VPS instance.

Endpoint: POST /vps/{vps_id}/actions

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "start"}' \
  https://api.lineserve.com/v1/vps/vps_123456/actions

Stop VPS

Stop a running VPS instance.

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "stop"}' \
  https://api.lineserve.com/v1/vps/vps_123456/actions

Restart VPS

Restart a VPS instance.

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "restart"}' \
  https://api.lineserve.com/v1/vps/vps_123456/actions

Resize VPS

Change the size of a VPS instance.

Parameters:

size (required): New instance size

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "resize",
    "size": "professional"
  }' \
  https://api.lineserve.com/v1/vps/vps_123456/actions

Create Snapshot

Create a snapshot of a VPS instance.

Parameters:

name (required): Snapshot name

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "snapshot",
    "name": "backup-2024-01-15"
  }' \
  https://api.lineserve.com/v1/vps/vps_123456/actions

Rebuild VPS

Rebuild a VPS instance with a new image.

Parameters:

image (required): New operating system image

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rebuild",
    "image": "ubuntu-22.04"
  }' \
  https://api.lineserve.com/v1/vps/vps_123456/actions

VPS Metrics

Get VPS Metrics

Retrieve performance metrics for a VPS instance.

Endpoint: GET /vps/{vps_id}/metrics

Parameters:

start (optional): Start time (ISO 8601 format)
end (optional): End time (ISO 8601 format)
interval (optional): Data interval (1m, 5m, 1h, 1d)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/vps/vps_123456/metrics?interval=5m"

Example Response:

{
  "metrics": {
    "cpu": [
      {"timestamp": "2024-01-15T12:00:00Z", "value": 25.5},
      {"timestamp": "2024-01-15T12:05:00Z", "value": 30.2}
    ],
    "memory": [
      {"timestamp": "2024-01-15T12:00:00Z", "value": 512},
      {"timestamp": "2024-01-15T12:05:00Z", "value": 520}
    ],
    "disk": [
      {"timestamp": "2024-01-15T12:00:00Z", "value": 15.2},
      {"timestamp": "2024-01-15T12:05:00Z", "value": 15.3}
    ],
    "network_in": [
      {"timestamp": "2024-01-15T12:00:00Z", "value": 1024},
      {"timestamp": "2024-01-15T12:05:00Z", "value": 2048}
    ],
    "network_out": [
      {"timestamp": "2024-01-15T12:00:00Z", "value": 512},
      {"timestamp": "2024-01-15T12:05:00Z", "value": 1024}
    ]
  }
}

Images

List Available Images

Get a list of available operating system images.

Endpoint: GET /images

Parameters:

type (optional): Filter by type (linux, windows)
distribution (optional): Filter by distribution

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/images

Example Response:

{
  "images": [
    {
      "id": "ubuntu-22.04",
      "name": "Ubuntu 22.04 LTS",
      "distribution": "ubuntu",
      "version": "22.04",
      "type": "linux",
      "description": "Ubuntu 22.04 LTS (Jammy Jellyfish)",
      "min_disk_size": 20,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "windows-server-2022",
      "name": "Windows Server 2022",
      "distribution": "windows",
      "version": "2022",
      "type": "windows",
      "description": "Windows Server 2022 Standard",
      "min_disk_size": 40,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Sizes

List Available Sizes

Get a list of available VPS sizes.

Endpoint: GET /sizes

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/sizes

Example Response:

{
  "sizes": [
    {
      "slug": "starter",
      "name": "Starter",
      "vcpus": 1,
      "memory": 1024,
      "disk": 25,
      "transfer": 1000,
      "price_monthly": 5.00,
      "price_hourly": 0.007,
      "available": true
    },
    {
      "slug": "professional",
      "name": "Professional",
      "vcpus": 2,
      "memory": 4096,
      "disk": 80,
      "transfer": 3000,
      "price_monthly": 20.00,
      "price_hourly": 0.030,
      "available": true
    }
  ]
}

Regions

List Available Regions

Get a list of available deployment regions.

Endpoint: GET /regions

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/regions

Example Response:

{
  "regions": [
    {
      "slug": "nairobi",
      "name": "Nairobi",
      "country": "Kenya",
      "continent": "Africa",
      "available": true,
      "features": ["vps", "databases", "storage", "kubernetes"]
    },
    {
      "slug": "cape-town",
      "name": "Cape Town",
      "country": "South Africa",
      "continent": "Africa",
      "available": true,
      "features": ["vps", "databases", "storage"]
    }
  ]
}

SSH Keys

List SSH Keys

Get a list of SSH keys in your account.

Endpoint: GET /ssh-keys

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/ssh-keys

Add SSH Key

Add a new SSH key to your account.

Endpoint: POST /ssh-keys

Parameters:

name (required): Key name
public_key (required): SSH public key content

Example Request:

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

Snapshots

List Snapshots

Get a list of VPS snapshots.

Endpoint: GET /snapshots

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/snapshots

Delete Snapshot

Delete a VPS snapshot.

Endpoint: DELETE /snapshots/{snapshot_id}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/snapshots/snapshot_123456

Error Handling

HTTP Status Codes

200 - Success
201 - Created
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Unprocessable Entity
429 - Rate Limited
500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "The request could not be processed",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

Rate Limiting

Rate Limit: 1000 requests per hour per API key
Headers: Rate limit information in response headers
Burst Limit: 100 requests per minute

Rate Limit Headers:

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

Pagination

Large result sets are paginated:

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 25, max: 100)

Response Meta:

{
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 25,
    "pages": 6
  }
}

Webhooks

Configure webhooks to receive real-time notifications:

Events:

vps.created
vps.started
vps.stopped
vps.deleted
vps.resized
snapshot.created
snapshot.deleted

Webhook Payload:

{
  "event": "vps.created",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "vps": {
      "id": "vps_123456",
      "name": "web-server",
      "status": "running"
    }
  }
}

SDKs and Libraries

Official SDKs available for:

Node.js: npm install @lineserve/node
Python: pip install lineserve
PHP: composer require lineserve/php
Go: go get github.com/lineserve/go

Base URL​

Authentication​

VPS Management​

List VPS Instances​

Create VPS Instance​

Get VPS Instance​

Update VPS Instance​

Delete VPS Instance​

VPS Actions​

Start VPS​

Stop VPS​

Restart VPS​

Resize VPS​

Create Snapshot​

Rebuild VPS​

VPS Metrics​

Get VPS Metrics​

Images​

List Available Images​

Sizes​

List Available Sizes​

Regions​

List Available Regions​

SSH Keys​

List SSH Keys​

Add SSH Key​

Snapshots​

List Snapshots​

Delete Snapshot​

Error Handling​

HTTP Status Codes​

Error Response Format​

Rate Limiting​

Pagination​

Webhooks​

SDKs and Libraries​

Next Steps​

Base URL

Authentication

VPS Management

List VPS Instances

Create VPS Instance

Get VPS Instance

Update VPS Instance

Delete VPS Instance

VPS Actions

Start VPS

Stop VPS

Restart VPS

Resize VPS

Create Snapshot

Rebuild VPS

VPS Metrics

Get VPS Metrics

Images

List Available Images

Sizes

List Available Sizes

Regions

List Available Regions

SSH Keys

List SSH Keys

Add SSH Key

Snapshots

List Snapshots

Delete Snapshot

Error Handling

HTTP Status Codes

Error Response Format

Rate Limiting

Pagination

Webhooks

SDKs and Libraries

Next Steps