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

Instances

GET /instances Returns a list of all active virtual machine instances for t... GET /instances/templates List all available VM templates that can be used when creati... POST /instances/launch-instance Creates a new instance using standardized configurations. Th... POST /instances/launch-custom Creates a fully customized Instance with exact resource spec... GET /instances/{id} Retrieves comprehensive details about a specific virtual mac... DELETE /instances/{id} Deletes an instance and releases all associated resources. GET /instances/available Lists all available instance types and their configurations,... PUT /instances/{id}/rename Updates the display name of an existing instance. GET /instances/{id}/stats Get real-time CPU, memory, disk I/O, and network statistics ... POST /instances/{id}/console Get a VNC proxy ticket for remote console access to the inst... POST /instances/log Retrieves instance history for the authenticated account wit...

Power

POST /instances/{id}/power-on Powers on a stopped instance. POST /instances/{id}/shutdown Performs a graceful shutdown of the specified instance. POST /instances/{id}/force-shutdown Immediate forced shutdown. Equivalent to pulling the power p... POST /instances/{id}/reboot Hard reboot of the instance. Stops and starts the VM. POST /instances/{id}/power-cycle Power cycle the instance (stop + start). Use after renaming ...

Backups

POST /instances/{id}/backup Create a backup of the instance. The instance continues runn... GET /instances/{id}/backups List all available backups for an instance. POST /instances/{id}/restore Restore an instance from a backup. **WARNING: This overwrite... GET /backups List all backups across all VMs for your account. DELETE /backups Delete a backup from PBS storage. This action cannot be undo... POST /backups/restore Restore a backup to any compatible VM. Useful for migrating ... GET /backups/storage Get total backup storage used by your account with billing b... PUT /backups/notes Update the notes for a backup. GET /instances/{id}/backup-schedule Get the automatic backup schedule for an instance. POST /instances/{id}/backup-schedule Create or update the automatic backup schedule for an instan... DELETE /instances/{id}/backup-schedule Delete the automatic backup schedule for an instance.

IP Addresses

GET /instances/{id}/ips Get all IP addresses assigned to an instance, including prim... POST /instances/{id}/ips Assign an additional IP address to an instance. The IP is se... DELETE /instances/{id}/ips/{ip_address} Release an additional IP address from an instance. The IP is...

Firewall

GET /instances/{id}/firewall Get current firewall configuration including enabled status,... PUT /instances/{id}/firewall Enable/disable firewall and set default inbound/outbound pol... POST /instances/{id}/firewall/rules Add a new firewall rule. Rules are evaluated in order (posit... GET /instances/{id}/firewall/rules/{pos} Get details of a specific firewall rule by position. DELETE /instances/{id}/firewall/rules/{pos} Delete a firewall rule by position. Subsequent rules shift p...

Teams

PUT /instances/{id}/team Assign an instance to a team for organization and access con... DELETE /instances/{id}/team Remove an instance from its assigned team. GET /teams/{team_id}/instances List all instances assigned to a specific team.

Tasks

GET /tasks List recent tasks for your account. GET /tasks/{id} Get status of an async task (instance creation, deletion, et...

System

GET /health Check API and service health status.

Endpoint Reference

GET /instances

Returns a list of all active virtual machine instances for the authenticated account.

Response
{
  "uuid": "vm-abc123",
  "name": "my-instance",
  "ip_address": "your.public.ip.address",
  "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 that can be used when 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/launch-instance

Creates a new instance using standardized configurations. This is the recommended way to launch instances.

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": "igl",
  "instance_type": "gpu_1x_a4000",
  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...",
  "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": "your.public.ip.address",
  "status": "PENDING"
}
POST /instances/launch-custom

Creates a fully customized Instance with exact resource specifications.

Parameters

Name Type Description
region required body Region to deploy in (e.g., 'igl')
vcpus required body Number of virtual CPU cores
memory_gib required body Memory in GiB
storage_gib required body Storage in GiB
gpu_count required body Number of GPUs (0 for CPU-only)
gpu_model body GPU model (e.g., 'A4000', 'A6000'). Required if gpu_count > 0
ssh_key required body SSH public key for access
name body Custom instance name
template_name body OS template name
Request Body
{
  "region": "igl",
  "vcpus": 16,
  "memory_gib": 64,
  "storage_gib": 500,
  "gpu_count": 2,
  "gpu_model": "A4000",
  "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...",
  "name": "custom-ml-server"
}
Response
{
  "task_id": "task_abc123",
  "vm_uuid": "vm_xyz789",
  "assigned_ip": "your.public.ip.address",
  "status": "PENDING"
}
GET /instances/{id}

Retrieves comprehensive details about a specific virtual machine instance.

Parameters

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

Deletes an instance and releases all associated resources.

Parameters

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

Lists all available instance types and their configurations, along with current capacity in regions.

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

Updates 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 for an instance.

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 to the instance.

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/log

Retrieves instance history for the authenticated account within the specified time range.

Parameters

Name Type Description
start_time body Start of time range (ISO 8601 format)
end_time body End of time range (ISO 8601 format)
instance_id body Filter by specific instance UUID
Response
{
  "logs": [
    {
      "instance_id": "vm-abc123",
      "event": "created",
      "timestamp": "2024-01-15T10:30:00Z",
      "details": {...}
    }
  ],
  "total": 1
}
POST /instances/{id}/power-on

Powers 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

Performs a graceful shutdown of the specified instance.

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 /backups

List all backups across all VMs for your account.

Response
{
  "backups": [
    {
      "volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z",
      "instance_id": "vm-abc123",
      "instance_name": "my-instance",
      "size_bytes": 48530000000,
      "size_human": "45.2 GB",
      "created_at": "2024-01-15T10:30:00Z",
      "notes": "Pre-upgrade backup"
    }
  ],
  "total": 1
}
DELETE /backups

Delete a backup from PBS storage. This action cannot be undone.

Parameters

Name Type Description
volid required query PBS volume ID of the backup to delete (from list backups)
Response
{
  "success": true,
  "message": "Backup deletion started",
  "task_id": "task_abc123",
  "volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z"
}
POST /backups/restore

Restore a backup to any compatible VM. Useful for migrating data between instances.

Parameters

Name Type Description
volid required body PBS volume ID of the backup to restore
target_instance_id required body UUID of the target instance to restore to
Response
{
  "message": "Restore started",
  "task_id": "task_abc123",
  "target_instance_id": "vm-xyz789",
  "backup_volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z"
}
GET /backups/storage

Get total backup storage used by your account with billing breakdown. Includes free tier (250GB) and billable overage.

Response
{
  "total_bytes": 107374182400,
  "total_gb": 100.0,
  "total_formatted": "100.00 GB",
  "free_tier_bytes": 268435456000,
  "free_tier_gb": 250.0,
  "billable_bytes": 0,
  "billable_gb": 0,
  "backup_count": 5,
  "monthly_cost_cents": 0,
  "monthly_cost_formatted": "$0.00/mo",
  "is_free": true,
  "usage_percent": 40.0
}
PUT /backups/notes

Update the notes for a backup.

Parameters

Name Type Description
volid required query PBS volume ID of the backup
notes required body New notes for the backup
Request Body
{
  "notes": "Pre-upgrade backup - stable version"
}
Response
{
  "success": true,
  "message": "Notes updated",
  "volid": "wil-pbs-01:backup/vm/100/2024-01-15T10:30:00Z"
}
GET /instances/{id}/backup-schedule

Get the automatic backup schedule for an instance.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "instance_id": "vm-abc123",
  "enabled": true,
  "frequency": "daily",
  "time_utc": "03:00",
  "retention_count": 7,
  "last_backup": "2024-01-15T03:00:00Z",
  "next_backup": "2024-01-16T03:00:00Z"
}
POST /instances/{id}/backup-schedule

Create or update the automatic backup schedule for an instance.

Parameters

Name Type Description
id required path Instance UUID
enabled body Enable or disable the schedule (default: true)
frequency body Backup frequency: 'daily', 'weekly', 'monthly'
time_utc body Time to run backup in UTC (e.g., '03:00')
retention_count body Number of backups to retain (default: 7)
Request Body
{
  "enabled": true,
  "frequency": "daily",
  "time_utc": "03:00",
  "retention_count": 7
}
Response
{
  "success": true,
  "message": "Backup schedule created",
  "instance_id": "vm-abc123",
  "schedule": {
    "enabled": true,
    "frequency": "daily",
    "time_utc": "03:00",
    "retention_count": 7
  }
}
DELETE /instances/{id}/backup-schedule

Delete the automatic backup schedule for an instance.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "success": true,
  "message": "Backup schedule deleted",
  "instance_id": "vm-abc123"
}
GET /instances/{id}/ips

Get all IP addresses assigned to an instance, including primary and additional IPs.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "instance_id": "abc-123",
  "ip_count": 2,
  "ips": [
    {
      "ip_address": "98.115.241.73",
      "internal_ip": "98.115.241.73",
      "interface_name": "net0",
      "is_primary": true,
      "bridge": "vmbr0",
      "mac_address": "bc:24:11:50:44:49",
      "assigned_at": "2026-01-15T10:30:00Z"
    },
    {
      "ip_address": "98.115.241.74",
      "internal_ip": "98.115.241.74",
      "interface_name": "net1",
      "is_primary": false,
      "bridge": "vmbr0",
      "mac_address": "bc:24:11:50:44:4a",
      "assigned_at": "2026-01-15T11:00:00Z"
    }
  ]
}
POST /instances/{id}/ips

Assign an additional IP address to an instance. The IP is selected from available IPs in the same region and whitelisted on the primary NIC via ipfilter. Configure as an alias on eth0 inside the VM (ip addr add X.X.X.X/32 dev eth0). Billed at $3.00/month.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "status": "success",
  "message": "IP 98.115.241.74 assigned (configure as alias on primary interface)",
  "ip": {
    "ip_address": "98.115.241.74",
    "internal_ip": "98.115.241.74",
    "interface_name": "net1",
    "bridge": "vmbr0",
    "mac_address": "bc:24:11:50:44:4a"
  }
}
DELETE /instances/{id}/ips/{ip_address}

Release an additional IP address from an instance. The IP is removed from the firewall whitelist. Cannot release the primary IP or the last remaining IP.

Parameters

Name Type Description
id required path Instance UUID
ip_address required path IP address to release (e.g. 98.115.241.74)
Response
{
  "status": "success",
  "message": "IP 98.115.241.74 released from net1",
  "released_ip": "98.115.241.74",
  "released_interface": "net1"
}
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"
}
PUT /instances/{id}/team

Assign an instance to a team for organization and access control.

Parameters

Name Type Description
id required path Instance UUID
team_id required body Team UUID to assign to
Request Body
{
  "team_id": "team-uuid-here"
}
Response
{
  "success": true,
  "message": "Instance assigned to team",
  "instance_id": "vm-abc123",
  "team_id": "team-uuid-here"
}
DELETE /instances/{id}/team

Remove an instance from its assigned team.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "success": true,
  "message": "Instance removed from team",
  "instance_id": "vm-abc123"
}
GET /teams/{team_id}/instances

List all instances assigned to a specific team.

Parameters

Name Type Description
team_id required path Team UUID
Response
{
  "team_id": "team-uuid-here",
  "team_name": "ML Team",
  "instances": [
    {
      "uuid": "vm-abc123",
      "name": "training-server",
      "ip_address": "your.public.ip.address",
      "power_status": "running"
    }
  ],
  "total": 1
}
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": "your.public.ip.address",
  "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