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.

API Endpoints

Instances

GET /instances List all active instances for your account. POST /instances Create a new instance using a standard configuration. GET /instances/{id} Get details for a specific instance. DELETE /instances/{id} Permanently delete an instance. **This action is irreversibl... POST /instances/{id}/reboot Perform a hard reboot of the specified instance. GET /instances/available List all available instance types with current capacity by r... PUT /instances/{id}/rename Update 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.

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...

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

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"
}
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
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"
  }
}
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"
}
POST /instances/{id}/reboot

Perform a hard reboot of the specified instance.

Parameters

Name Type Description
id required path Instance UUID
Response
{
  "task_id": "task_abc123",
  "status": "PENDING",
  "message": "VM reboot queued",
  "instance_id": "vm-abc123"
}
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}/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 /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