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.

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