Blue Lobster API

Programmatically create, manage, and delete GPU and CPU instances.

Base URL: https://api.bluelobster.ai/api/v1

All endpoints require authentication via X-API-Key header. Log in to create API keys.

OpenAPI Spec - Import into Postman, Insomnia, or other API tools.

API Endpoints

Endpoint Reference

GET /instances

List all active instances for your account.

Response
{
  "uuid": "vm-abc123",
  "name": "my-instance",
  "ip_address": "192.168.1.100",
  "cpu_cores": 8,
  "memory": 32,
  "storage": 100,
  "gpu_count": 1,
  "gpu_model": "RTX A4000",
  "power_status": "running",
  "created_at": "2024-01-15T10:30:00Z"
}
GET /instances/templates

List all available VM templates for creating instances.

Response
{
  "templates": [
    {
      "name": "UBUNTU-22-04",
      "vmid": 100,
      "display_name": "Ubuntu 22.04 Server",
      "os_type": "linux",
      "has_nvidia": false
    },
    {
      "name": "UBUNTU-22-04-NV-DK",
      "vmid": 101,
      "display_name": "Ubuntu 22.04 + NVIDIA + Docker",
      "os_type": "linux",
      "has_nvidia": true
    }
  ],
  "total": 2
}
POST /instances

Create a new instance using a standard configuration.

Parameters

Name Type Description
region required body Region to deploy in (e.g., 'us-east-1')
instance_type required body Instance type (e.g., 'gpu_1x_a4000')
ssh_key required body SSH public key for access
name body Custom instance name
username body Login username (default: ubuntu)
metadata body Key-value pairs for organization
template_name body OS template (e.g., 'UBUNTU-22-04-NV'). Use /instances/templates to list. Defaults: NVIDIA template for GPU instances, base for CPU.
iso_url body ISO URL for custom OS (max 4GB). Use instead of template_name for Windows, SteamOS, etc. VM boots from ISO for installation.
Request Body
{
  "region": "us-east-1",
  "instance_type": "gpu_1x_a4000",
  "ssh_key": "ssh-rsa AAAA...",
  "name": "my-gpu-instance",
  "username": "ubuntu",
  "metadata": {
    "project": "ml-training"
  },
  "template_name": "UBUNTU-22-04-NV"
}
Response
{
  "task_id": "task_abc123",
  "vm_uuid": "vm_xyz789",
  "assigned_ip": "192.168.1.100",
  "status": "PENDING"
}
GET /instances/{id}

Get details for a specific instance.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "uuid": "vm-abc123",
  "name": "my-instance",
  "ip_address": "192.168.1.100",
  "cpu_cores": 8,
  "memory": 32,
  "storage": 100,
  "gpu_count": 1,
  "gpu_model": "RTX A4000",
  "power_status": "running",
  "region": "us-east-1",
  "created_at": "2024-01-15T10:30:00Z"
}
DELETE /instances/{id}

Permanently delete an instance. **This action is irreversible.**

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "Instance deletion queued"
}
GET /instances/available

List all available instance types with current capacity by region.

Response
{
  "data": [
    {
      "id": "gpu_1x_a4000",
      "instance_type": {
        "name": "gpu_1x_a4000",
        "description": "Single GPU Instance",
        "price_cents_per_hour": 45,
        "specs": {
          "vcpus": 8,
          "memory_gib": 32,
          "storage_gib": 250,
          "gpus": 1,
          "gpu_model": "A4000"
        }
      },
      "regions_with_capacity_available": [...]
    }
  ]
}
PUT /instances/{id}/rename

Update the display name of an existing instance.

Parameters

Name Type Description
id required path Instance UUID
name required body New name (3-64 chars, alphanumeric with hyphens/underscores)
Request Body
{
  "name": "my-production-server"
}
Response
{
  "message": "Instance renamed successfully",
  "instance_id": "vm-abc123",
  "new_name": "my-production-server"
}
GET /instances/{id}/stats

Get real-time CPU, memory, disk I/O, and network statistics.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "instance_id": "vm-abc123",
  "status": "running",
  "cpu": {"usage_percent": 25.5, "cores": 8},
  "memory": {
    "used_bytes": 8589934592,
    "total_bytes": 17179869184,
    "usage_percent": 50.0
  },
  "disk": {"read_bytes_sec": 1048576, "write_bytes_sec": 524288},
  "network": {"in_bytes_sec": 102400, "out_bytes_sec": 51200},
  "uptime_seconds": 86400
}
POST /instances/{id}/console

Get a VNC proxy ticket for remote console access.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "instance_id": "vm-abc123",
  "ticket": "PVEVNC:...",
  "port": 5900,
  "host": "phl-gpu-01.bluelobster.ai"
}
POST /instances/{id}/power-on

Power on a stopped instance.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "VM power on queued",
  "instance_id": "vm-abc123"
}
POST /instances/{id}/shutdown

Graceful shutdown of the instance. Sends ACPI shutdown signal to the OS.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "VM shutdown queued",
  "instance_id": "vm-abc123"
}
POST /instances/{id}/force-shutdown

Immediate forced shutdown. Equivalent to pulling the power plug. **May cause data loss.**

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "VM force shutdown queued",
  "instance_id": "vm-abc123"
}
POST /instances/{id}/reboot

Hard reboot of the instance. Stops and starts the VM.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "VM reboot queued",
  "instance_id": "vm-abc123"
}
POST /instances/{id}/power-cycle

Power cycle the instance (stop + start). Use after renaming for hostname changes to take effect.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "VM power cycle queued",
  "instance_id": "vm-abc123"
}
POST /instances/{id}/backup

Create a backup of the instance. The instance continues running during backup.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "message": "Backup started",
  "task_id": "task_abc123",
  "instance_id": "vm-abc123"
}
GET /instances/{id}/backups

List all available backups for an instance.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "instance_id": "vm-abc123",
  "storage": "wil-pbs-01",
  "backups": [
    {
      "volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z",
      "size_bytes": 48530000000,
      "size_human": "45.2 GB",
      "created_at": "2024-01-15T10:30:00Z",
      "format": "pbs-vm"
    }
  ],
  "total": 1,
  "backup_in_progress": null,
  "restore_in_progress": null
}
POST /instances/{id}/restore

Restore an instance from a backup. **WARNING: This overwrites all current data.**

Parameters

Name Type Description
id required path Instance UUID
backup_volid required body Volume ID of backup to restore (from list backups)
Request Body
{
  "backup_volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z"
}
Response
{
  "message": "Restore started",
  "task_id": "task_abc123",
  "instance_id": "vm-abc123",
  "backup_volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z"
}
GET /instances/{id}/firewall

Get current firewall configuration including enabled status, policies, and rules.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "enabled": true,
  "policy_in": "DROP",
  "policy_out": "ACCEPT",
  "rules": [
    {
      "pos": 0,
      "type": "in",
      "action": "ACCEPT",
      "proto": "tcp",
      "dport": "22",
      "comment": "SSH access",
      "enable": 1
    }
  ]
}
PUT /instances/{id}/firewall

Enable/disable firewall and set default inbound/outbound policies.

Parameters

Name Type Description
id required path Instance UUID
enable body Enable (true) or disable (false) firewall
policy_in body Default inbound policy: ACCEPT or DROP
policy_out body Default outbound policy: ACCEPT or DROP
Request Body
{
  "enable": true,
  "policy_in": "DROP",
  "policy_out": "ACCEPT"
}
Response
{
  "status": "success",
  "message": "Firewall options updated",
  "firewall": {
    "enabled": true,
    "policy_in": "DROP",
    "policy_out": "ACCEPT",
    "rules": []
  }
}
POST /instances/{id}/firewall/rules

Add a new firewall rule. Rules are evaluated in order (position 0 first).

Parameters

Name Type Description
id required path Instance UUID
type required body Direction: 'in' or 'out'
action required body Action: ACCEPT, DROP, or REJECT
proto body Protocol: tcp, udp, icmp (default: tcp)
dport body Destination port(s): 22, 80:443, or 80,443
sport body Source port(s)
source body Source IP/CIDR (e.g., 192.168.1.0/24)
dest body Destination IP/CIDR
comment body Rule description
enable body 1=enabled (default), 0=disabled
Request Body
{
  "type": "in",
  "action": "ACCEPT",
  "proto": "tcp",
  "dport": "22",
  "comment": "SSH access"
}
Response
{
  "status": "success",
  "message": "Firewall rule added",
  "rule": {
    "pos": 0,
    "type": "in",
    "action": "ACCEPT",
    "proto": "tcp",
    "dport": "22",
    "comment": "SSH access"
  }
}
GET /instances/{id}/firewall/rules/{pos}

Get details of a specific firewall rule by position.

Parameters

Name Type Description
id required path Instance UUID
pos required path Rule position (0-based)
Response
{
  "pos": 0,
  "type": "in",
  "action": "ACCEPT",
  "proto": "tcp",
  "dport": "22",
  "source": "10.0.0.0/8",
  "comment": "SSH from private network",
  "enable": 1
}
DELETE /instances/{id}/firewall/rules/{pos}

Delete a firewall rule by position. Subsequent rules shift positions.

Parameters

Name Type Description
id required path Instance UUID
pos required path Rule position (0-based)
Response
{
  "status": "success",
  "message": "Firewall rule at position 0 deleted"
}
GET /tasks

List recent tasks for your account.

Parameters

Name Type Description
limit query Max results (default: 50, max: 100)
days query Days to look back (default: 1, max: 7)
status query Filter: PENDING, PROCESSING, COMPLETED, FAILED
Response
{
  "tasks": [
    {
      "task_id": "task_abc123",
      "status": "COMPLETED",
      "operation": "create_instance",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50
}
GET /tasks/{id}

Get status of an async task (instance creation, deletion, etc.).

Parameters

Name Type Description
id required path Task ID
Response
{
  "task_id": "task_abc123",
  "status": "COMPLETED",
  "operation": "create_instance",
  "vm_uuid": "vm_xyz789",
  "ip_address": "192.168.1.100",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:32:00Z"
}
GET /health

Check API and service health status.

Response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}

Reference

Task States

Async operations return a task_id. Poll the task endpoint to check status:

PENDINGTask queued for processing
PROCESSINGTask actively executing
COMPLETEDTask finished successfully
FAILEDTask encountered an error

Recommended polling interval: 2-5 seconds

Error Handling

All errors return JSON with error and message fields:

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

Status Codes

400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Resource unavailable
500Server Error