Forge API Reference

The Forge API enables programmatic management of cloud infrastructure instances, including SCADA systems, IoT platforms, and industrial applications. Manage the complete instance lifecycle from provisioning to destruction.

Authentication

All Forge API endpoints require authentication via API token:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Pricing Information

Get Public Pricing

GET /api/v1/forge/pricing

This endpoint is publicly accessible and does not require authentication.

Response:

{
  "instance_sizes": [
    {
      "size": "small",
      "vcpu": 2,
      "memory_gb": 4,
      "storage_gb": 50,
      "monthly_price": 49.00,
      "annual_price": 499.00,
      "annual_discount": 15
    },
    {
      "size": "medium", 
      "vcpu": 4,
      "memory_gb": 8,
      "storage_gb": 100,
      "monthly_price": 89.00,
      "annual_price": 905.00,
      "annual_discount": 15
    },
    {
      "size": "large",
      "vcpu": 8,
      "memory_gb": 16,
      "storage_gb": 200,
      "monthly_price": 149.00,
      "annual_price": 1515.00,
      "annual_discount": 15
    },
    {
      "size": "xlarge",
      "vcpu": 16,
      "memory_gb": 32,
      "storage_gb": 500,
      "monthly_price": 249.00,
      "annual_price": 2535.00,
      "annual_discount": 15
    },
    {
      "size": "dedicated",
      "vcpu": 8,
      "memory_gb": 16,
      "storage_gb": 1000,
      "storage_type": "NVMe",
      "monthly_price": 199.00,
      "annual_price": 2025.00,
      "annual_discount": 15
    }
  ],
  "regions": [
    {
      "id": "us-east",
      "name": "US East",
      "location": "Ashburn, Virginia",
      "provider": "AWS us-east-1"
    },
    {
      "id": "us-west",
      "name": "US West", 
      "location": "Hillsboro, Oregon",
      "provider": "AWS us-west-2"
    },
    {
      "id": "eu-central",
      "name": "EU Central",
      "location": "Falkenstein, Germany", 
      "provider": "Hetzner fsn1"
    },
    {
      "id": "eu-north",
      "name": "EU North",
      "location": "Helsinki, Finland",
      "provider": "Hetzner hel1"
    },
    {
      "id": "apac",
      "name": "APAC",
      "location": "Singapore",
      "provider": "AWS ap-southeast-1"
    }
  ],
  "applications": [
    {
      "id": "ignition-scada",
      "name": "Ignition SCADA",
      "description": "Industrial automation and SCADA development platform"
    },
    {
      "id": "node-red",
      "name": "Node-RED",
      "description": "Flow-based programming for IoT and automation"
    },
    {
      "id": "mosquitto-mqtt",
      "name": "Mosquitto MQTT",
      "description": "Lightweight MQTT broker for IoT messaging"
    },
    {
      "id": "grafana-influxdb",
      "name": "Grafana + InfluxDB",
      "description": "Time-series visualization and analytics"
    },
    {
      "id": "breakwater-ai",
      "name": "Breakwater AI (DGX Spark)",
      "description": "GPU-accelerated machine learning platform"
    }
  ]
}

Instance Management

List Instances

GET /api/v1/forge/instances

Query Parameters:

status (optional): Filter by status (provisioning, running, stopped, destroying, destroyed)
application (optional): Filter by application type
region (optional): Filter by region
limit (optional): Maximum number of results (default: 50)
offset (optional): Pagination offset (default: 0)

Response:

{
  "instances": [
    {
      "id": "instance_abc123",
      "name": "production-scada-01",
      "application": "ignition-scada",
      "size": "medium",
      "region": "us-east",
      "status": "running",
      "ip_address": "54.123.45.67",
      "fqdn": "production-scada-01.forge.techgonecoastal.com",
      "gateway_connected": true,
      "created_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:45:00Z",
      "monthly_cost": 89.00,
      "usage_hours": 148.5
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create Instance

POST /api/v1/forge/instances

Request Body:

{
  "name": "development-nodered-01",
  "application": "node-red",
  "size": "small",
  "region": "us-west",
  "description": "Development Node-RED instance",
  "gateway_auto_connect": true,
  "backup_enabled": true,
  "backup_frequency": "daily"
}

Response:

{
  "id": "instance_def456",
  "name": "development-nodered-01",
  "application": "node-red",
  "size": "small",
  "region": "us-west",
  "status": "provisioning",
  "estimated_ready_time": "2024-01-21T11:15:00Z",
  "created_at": "2024-01-21T11:00:00Z"
}

Get Instance Details

GET /api/v1/forge/instances/{instance_id}

Response:

{
  "id": "instance_abc123",
  "name": "production-scada-01",
  "description": "Production SCADA server",
  "application": "ignition-scada",
  "size": "medium",
  "region": "us-east",
  "status": "running",
  "ip_address": "54.123.45.67",
  "private_ip": "10.0.1.100",
  "fqdn": "production-scada-01.forge.techgonecoastal.com",
  "gateway_connected": true,
  "gateway_auto_connect": true,
  "ssl_certificate": {
    "issued": "2024-01-15T10:45:00Z",
    "expires": "2024-04-15T10:45:00Z",
    "issuer": "Let's Encrypt"
  },
  "specifications": {
    "vcpu": 4,
    "memory_gb": 8,
    "storage_gb": 100,
    "storage_type": "SSD"
  },
  "networking": {
    "public_ip": "54.123.45.67",
    "private_ip": "10.0.1.100",
    "ports": [
      {
        "port": 80,
        "protocol": "HTTP",
        "service": "Ignition HTTP"
      },
      {
        "port": 443,
        "protocol": "HTTPS",
        "service": "Ignition HTTPS"
      },
      {
        "port": 8088,
        "protocol": "HTTPS",
        "service": "Ignition Gateway"
      }
    ]
  },
  "backup_configuration": {
    "enabled": true,
    "frequency": "daily",
    "retention_days": 30,
    "last_backup": "2024-01-21T02:00:00Z"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:45:00Z",
  "billing": {
    "monthly_cost": 89.00,
    "usage_hours": 148.5,
    "current_month_cost": 16.85
  }
}

Update Instance

PATCH /api/v1/forge/instances/{instance_id}

Request Body:

{
  "name": "production-scada-01-updated",
  "description": "Updated production SCADA server",
  "backup_enabled": true,
  "backup_frequency": "weekly"
}

Response:

{
  "id": "instance_abc123",
  "name": "production-scada-01-updated",
  "description": "Updated production SCADA server",
  "updated_at": "2024-01-21T11:30:00Z"
}

Delete Instance

DELETE /api/v1/forge/instances/{instance_id}

Query Parameters:

force (optional): Force deletion without confirmation (default: false)

Response:

{
  "message": "Instance deletion initiated",
  "id": "instance_abc123",
  "status": "destroying",
  "estimated_completion": "2024-01-21T11:45:00Z"
}

Instance Snapshots

Create Snapshot

POST /api/v1/forge/instances/{instance_id}/snapshots

Request Body:

{
  "name": "before-upgrade-snapshot",
  "description": "Pre-upgrade backup snapshot"
}

Response:

{
  "snapshot_id": "snap_789",
  "name": "before-upgrade-snapshot",
  "status": "creating",
  "estimated_completion": "2024-01-21T11:20:00Z",
  "created_at": "2024-01-21T11:15:00Z"
}

List Snapshots

GET /api/v1/forge/instances/{instance_id}/snapshots

Response:

{
  "snapshots": [
    {
      "snapshot_id": "snap_789",
      "name": "before-upgrade-snapshot",
      "description": "Pre-upgrade backup snapshot",
      "status": "available",
      "size_gb": 8.5,
      "created_at": "2024-01-21T11:15:00Z",
      "completed_at": "2024-01-21T11:18:00Z"
    }
  ]
}

Delete Snapshot

DELETE /api/v1/forge/instances/{instance_id}/snapshots/{snapshot_id}

Response:

{
  "message": "Snapshot deleted successfully",
  "snapshot_id": "snap_789"
}

Instance Operations

Get Instance Backups

GET /api/v1/forge/instances/{instance_id}/backups

Response:

{
  "backups": [
    {
      "backup_id": "backup_456",
      "type": "automated",
      "status": "completed",
      "size_gb": 12.3,
      "created_at": "2024-01-21T02:00:00Z",
      "retention_until": "2024-02-20T02:00:00Z"
    }
  ]
}

Get Instance Events

GET /api/v1/forge/instances/{instance_id}/events

Query Parameters:

event_type (optional): Filter by event type
start_date (optional): Start date for event range
end_date (optional): End date for event range

Response:

{
  "events": [
    {
      "event_id": "event_123",
      "event_type": "instance_started",
      "timestamp": "2024-01-21T11:00:00Z",
      "message": "Instance started successfully",
      "details": {
        "previous_status": "stopped",
        "new_status": "running"
      }
    }
  ]
}

Get Console Access

POST /api/v1/forge/instances/{instance_id}/console

Response:

{
  "console_url": "https://console.forge.techgonecoastal.com/session/abc123",
  "session_id": "session_abc123",
  "expires_at": "2024-01-21T15:00:00Z",
  "access_method": "browser_vnc"
}

Get Connection Information

GET /api/v1/forge/instances/{instance_id}/connection

Response:

{
  "ssh": {
    "host": "production-scada-01.forge.techgonecoastal.com",
    "port": 22,
    "username": "ubuntu",
    "key_name": "forge-keypair"
  },
  "web_console": {
    "url": "https://production-scada-01.forge.techgonecoastal.com",
    "port": 443,
    "protocol": "https"
  },
  "application_endpoints": {
    "ignition_gateway": "https://production-scada-01.forge.techgonecoastal.com:8088",
    "ignition_web": "https://production-scada-01.forge.techgonecoastal.com"
  },
  "gateway_tunnel": {
    "status": "connected",
    "local_endpoint": "10.0.1.100",
    "connected_since": "2024-01-15T10:50:00Z"
  }
}

Toggle Gateway Connection

POST /api/v1/forge/instances/{instance_id}/toggle-gateway

Request Body:

{
  "enabled": false,
  "reason": "Temporary isolation for testing"
}

Response:

{
  "gateway_connected": false,
  "previous_status": "connected",
  "changed_at": "2024-01-21T11:45:00Z",
  "reason": "Temporary isolation for testing"
}

Error Handling

Standard Error Response

{
  "error": {
    "code": "INSTANCE_NOT_FOUND",
    "message": "Instance with ID instance_abc123 not found",
    "details": {
      "instance_id": "instance_abc123"
    }
  }
}

Common Error Codes

INSTANCE_NOT_FOUND: Instance ID does not exist
INVALID_INSTANCE_SIZE: Specified size not available
REGION_UNAVAILABLE: Selected region not available
QUOTA_EXCEEDED: Account instance limit exceeded
INSTANCE_NOT_RUNNING: Operation requires running instance
SNAPSHOT_LIMIT_EXCEEDED: Maximum snapshots per instance reached
BACKUP_IN_PROGRESS: Cannot perform operation during backup
INSUFFICIENT_PERMISSIONS: API token lacks required permissions

Instance Lifecycle States

State	Description	Available Operations
provisioning	Instance being created	View status
running	Fully operational	Start, stop, snapshot, backup, console
stopped	Powered down	Start, destroy, snapshot
destroying	Being permanently deleted	View status
destroyed	Permanently deleted	None

Rate Limiting

The Forge API implements rate limiting:

Instance Operations: 100 operations per hour per organization
API Requests: 1000 requests per hour per API token
Console Sessions: Maximum 5 concurrent console sessions

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995  
X-RateLimit-Reset: 1642770000

Authentication​

Pricing Information​

Get Public Pricing​

Instance Management​

List Instances​

Create Instance​

Get Instance Details​

Update Instance​

Delete Instance​

Instance Snapshots​

Create Snapshot​

List Snapshots​

Delete Snapshot​

Instance Operations​

Get Instance Backups​

Get Instance Events​

Get Console Access​

Get Connection Information​

Toggle Gateway Connection​

Error Handling​

Standard Error Response​

Common Error Codes​

Instance Lifecycle States​

Rate Limiting​

Authentication

Pricing Information

Get Public Pricing

Instance Management

List Instances

Create Instance

Get Instance Details

Update Instance

Delete Instance

Instance Snapshots

Create Snapshot

List Snapshots

Delete Snapshot

Instance Operations

Get Instance Backups

Get Instance Events

Get Console Access

Get Connection Information

Toggle Gateway Connection

Error Handling

Standard Error Response

Common Error Codes

Instance Lifecycle States

Rate Limiting