Hubfly spaceDocs
Console

Cell API · Dashboard

Containers & runtime

Create, configure, control, inspect, execute commands in and remove Cell containers.

Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.

How to use these endpoints

  1. Create a Cell project and choose a region before creating a container.
  2. Create from an image or build output, then read the container until its state settles.
  3. Use runtime logs, metrics or a session to diagnose startup; control and config changes require project permissions.

List containers

curl
curl "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/containers" \
  -H "Authorization: Bearer $HUBFLY_TOKEN"

The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.

Endpoint reference

Dashboard endpoints (14)

These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.

Open interactive API explorer
MethodPathPurpose
POST/api/v1/projects/:projectId/containers/createCreate and deploy a new container in a project
GET/api/v1/projects/:projectId/containersList all containers in a project with a status summary
PATCH/api/v1/projects/:projectId/containers/:containerId/configUpdate a container's resources, env vars, or runtime config
POST/api/v1/projects/:projectId/containers/:containerId/controlStart, stop, or restart a container
POST/api/v1/projects/:projectId/containers/:containerId/execRun a one-off command inside a running container
GET/api/v1/projects/:projectId/containers/:containerIdGet full configuration and status details for a container
GET/api/v1/projects/:projectId/containers/:containerId/logsFetch recent stdout/stderr output from the container runtime
GET/api/v1/projects/:projectId/containers/:containerId/metricsGet current and historical CPU/memory/disk/network stats
DELETE/api/v1/projects/:projectId/containers/:containerId/removePermanently delete a container and its runtime
GET/api/v1/projects/:projectId/containers/:containerId/replicate/contextGet suggested settings before replicating a container
POST/api/v1/projects/:projectId/containers/:containerId/replicateClone a container, either standalone or into a scaled group
POST/api/v1/projects/:projectId/containers/:containerId/runtimePoll the live runtime for a container's real-time status
POST/api/v1/projects/:projectId/containers/:containerId/sessionCreate a container session
POST/api/v1/projects/:projectId/containers/:containerId/terminal/sessionOpen a new interactive terminal (shell) session for a container
POSTCreate and deploy a new container in a projectDetails +/api/v1/projects/:projectId/containers/create

Creates a container from a Docker image, optionally one from the project's private registry, and starts provisioning it on the project's network. The container starts in a "deploying" status and transitions to running or error asynchronously.

  • The container name must be unique within the project.
  • Requires sufficient account balance and available free-tier compute allowance before a shared-tier container can run.
  • Environment variable values marked as secrets are encrypted at rest.
  • Any requested block-storage volumes are reserved for the container.
  • Requires container:create permission on the project.
  • If provisioning fails, the container is marked as errored rather than left in an inconsistent state.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
kindservice | jobNo
tiershared | dedicated_sleepable | dedicated_24x7 | auto_scaling | docker-osNo
sourceobjectYes
resourcesobjectYes
runtimeobjectNo
securityobjectNo
processobjectNo
healthcheckobjectNo
restartPolicyobjectNo
labelsobjectNo
portsobject[]No
networkAliasesstring[]No
networkAliasIdstringNo
environmentVariablesobject[]No
volumeMountsobject[]No
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "service",
        "job"
      ]
    },
    "tier": {
      "type": "string",
      "enum": [
        "shared",
        "dedicated_sleepable",
        "dedicated_24x7",
        "auto_scaling",
        "docker-os"
      ]
    },
    "source": {
      "type": "object",
      "properties": {
        "type": {
          "const": "docker",
          "type": "string"
        },
        "dockerImage": {
          "type": "string"
        },
        "registryCredentialId": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "dockerImage"
      ],
      "additionalProperties": false
    },
    "resources": {
      "type": "object",
      "properties": {
        "cpu": {
          "type": "number"
        },
        "ram": {
          "type": "number"
        },
        "storage": {
          "type": "number"
        }
      },
      "required": [
        "cpu",
        "ram",
        "storage"
      ],
      "additionalProperties": false
    },
    "runtime": {
      "type": "object",
      "properties": {
        "autoSleep": {
          "type": "boolean"
        },
        "autoScale": {
          "type": "boolean"
        },
        "is24x7": {
          "type": "boolean"
        },
        "autoScaleMode": {
          "type": "string",
          "enum": [
            "vertical",
            "horizontal"
          ]
        },
        "autoScaleMaxCpu": {
          "type": "number"
        },
        "autoScaleMaxRam": {
          "type": "number"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "security": {
      "type": "object",
      "properties": {
        "dropCapabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "addCapabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "seccompProfile": {
          "type": "string"
        },
        "noNewPrivileges": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "process": {
      "type": "object",
      "properties": {
        "command": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "entrypoint": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "workingDir": {
          "type": "string"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "healthcheck": {
      "type": "object",
      "properties": {
        "test": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "interval": {
          "type": "string"
        },
        "timeout": {
          "type": "string"
        },
        "startPeriod": {
          "type": "string"
        },
        "retries": {
          "type": "number"
        }
      },
      "required": [
        "test"
      ],
      "additionalProperties": false
    },
    "restartPolicy": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "enum": [
            "always",
            "no",
            "unless-stopped",
            "on-failure"
          ]
        },
        "maximumRetryCount": {
          "type": "number"
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false
    },
    "labels": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "ports": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "protocol": {
            "type": "string",
            "enum": [
              "http",
              "tcp",
              "udp"
            ]
          },
          "container": {
            "type": "number"
          },
          "publicPort": {
            "type": "number"
          }
        },
        "required": [
          "protocol",
          "container"
        ],
        "additionalProperties": false
      }
    },
    "networkAliases": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "networkAliasId": {
      "type": "string"
    },
    "environmentVariables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "isSecret": {
            "type": "boolean"
          }
        },
        "required": [
          "key",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "volumeMounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "volumeId": {
            "type": "string"
          },
          "mountPoint": {
            "type": "string"
          },
          "readOnly": {
            "type": "boolean"
          }
        },
        "required": [
          "volumeId",
          "mountPoint"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "name",
    "source",
    "resources"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "kind": {
              "type": "string",
              "enum": [
                "service",
                "job"
              ]
            },
            "tier": {
              "type": "string",
              "enum": [
                "shared",
                "dedicated_sleepable",
                "dedicated_24x7",
                "auto_scaling",
                "docker-os"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "building",
                "stopped",
                "running",
                "deploying",
                "sleeping",
                "error",
                "deleting"
              ]
            },
            "runtimeId": {
              "type": "string"
            },
            "createdAt": {
              "type": "string",
              "description": "Date string"
            }
          },
          "required": [
            "id",
            "projectId",
            "name",
            "kind",
            "tier",
            "status",
            "runtimeId",
            "createdAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "id": "string",
        "projectId": "string",
        "name": "string",
        "kind": "service",
        "tier": "shared",
        "status": "pending",
        "runtimeId": "string",
        "createdAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList all containers in a project with a status summaryDetails +/api/v1/projects/:projectId/containers

Returns every container belonging to a project along with a summary count of how many are running, stopped, or need attention (error/deleting).

  • Requires container:logs permission on the project.
  • Also accessible to callers whose project access is hibernating.
  • Only high-level fields are returned; use the single-container detail endpoint for full configuration.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "service",
                      "job"
                    ]
                  },
                  "tier": {
                    "type": "string",
                    "enum": [
                      "shared",
                      "dedicated_sleepable",
                      "dedicated_24x7",
                      "auto_scaling",
                      "docker-os"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "building",
                      "stopped",
                      "running",
                      "deploying",
                      "sleeping",
                      "error",
                      "deleting"
                    ]
                  },
                  "sourceType": {
                    "type": "string",
                    "enum": [
                      "git",
                      "docker",
                      "template"
                    ]
                  },
                  "sourceLabel": {
                    "type": "string"
                  },
                  "resources": {
                    "type": "object",
                    "properties": {
                      "cpu": {
                        "type": "number"
                      },
                      "ram": {
                        "type": "number"
                      },
                      "storage": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "cpu",
                      "ram",
                      "storage"
                    ],
                    "additionalProperties": false
                  },
                  "runtime": {
                    "type": "object",
                    "properties": {
                      "autoSleep": {
                        "type": "boolean"
                      },
                      "autoScale": {
                        "type": "boolean"
                      },
                      "is24x7": {
                        "type": "boolean"
                      },
                      "autoScaleMode": {
                        "type": "string",
                        "enum": [
                          "vertical",
                          "horizontal"
                        ]
                      },
                      "autoScaleMaxCpu": {
                        "type": "number"
                      },
                      "autoScaleMaxRam": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "autoSleep",
                      "autoScale",
                      "is24x7"
                    ],
                    "additionalProperties": false
                  },
                  "guardHold": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "scope": {
                        "type": "string",
                        "enum": [
                          "project",
                          "container"
                        ]
                      },
                      "containerId": {
                        "type": "string",
                        "nullable": true
                      },
                      "projectId": {
                        "type": "string"
                      },
                      "reasonCategory": {
                        "type": "string",
                        "enum": [
                          "cryptomining",
                          "proxy_abuse",
                          "network_abuse",
                          "reverse_shell",
                          "spam",
                          "malware",
                          "resource_abuse",
                          "crash_loop",
                          "policy",
                          "other"
                        ]
                      },
                      "severity": {
                        "type": "string",
                        "enum": [
                          "low",
                          "medium",
                          "high",
                          "critical"
                        ]
                      },
                      "summary": {
                        "type": "string"
                      },
                      "publicMessage": {
                        "type": "string",
                        "nullable": true
                      },
                      "placedAt": {
                        "type": "string"
                      },
                      "contact": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "scope",
                      "containerId",
                      "projectId",
                      "reasonCategory",
                      "severity",
                      "summary",
                      "publicMessage",
                      "placedAt",
                      "contact"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  },
                  "updatedAt": {
                    "type": "string",
                    "description": "Date string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "kind",
                  "tier",
                  "status",
                  "sourceType",
                  "sourceLabel",
                  "resources",
                  "runtime",
                  "guardHold",
                  "createdAt",
                  "updatedAt"
                ],
                "additionalProperties": false
              }
            },
            "summary": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "number"
                },
                "running": {
                  "type": "number"
                },
                "stopped": {
                  "type": "number"
                },
                "attention": {
                  "type": "number"
                }
              },
              "required": [
                "total",
                "running",
                "stopped",
                "attention"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "items",
            "summary"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "items": [
          {
            "id": "string",
            "name": "string",
            "kind": "service",
            "tier": "shared",
            "status": "pending",
            "sourceType": "git",
            "sourceLabel": "string",
            "resources": {
              "cpu": 0,
              "ram": 0,
              "storage": 0
            },
            "runtime": {
              "autoSleep": true,
              "autoScale": true,
              "is24x7": true,
              "autoScaleMode": "vertical",
              "autoScaleMaxCpu": 0,
              "autoScaleMaxRam": 0
            },
            "guardHold": {
              "id": "string",
              "scope": "project",
              "containerId": "string",
              "projectId": "string",
              "reasonCategory": "cryptomining",
              "severity": "low",
              "summary": "string",
              "publicMessage": "string",
              "placedAt": "string",
              "contact": "string"
            },
            "createdAt": "string",
            "updatedAt": "string"
          }
        ],
        "summary": {
          "total": 0,
          "running": 0,
          "stopped": 0,
          "attention": 0
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
PATCHUpdate a container's resources, env vars, or runtime configDetails +/api/v1/projects/:projectId/containers/:containerId/config

Applies a partial update to a container's process command, labels, resources/tier, security options, healthcheck, networking, or environment variables. Changes are merged into the existing configuration rather than replacing it wholesale.

  • Depending on what changed, the update may resize resources or grow storage on the live runtime.
  • For git-sourced containers, changing a build-scoped environment variable can trigger an image rebuild.
  • If the container is currently running, some changes are applied via a live config redeploy.
  • If that redeploy fails, the update is undone and an error is returned instead of leaving a partial change.
  • Requires container:update permission.
  • Also allowed while the project is hibernating.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
environmentVariablesobject[]No
envCategorizationEnabledbooleanNo
forceRebuildbooleanNo
processobjectNo
labelsobjectNo
resourcesobjectNo
securityobjectNo
healthcheckobjectNo
networkingobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "environmentVariables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "isSecret": {
            "type": "boolean"
          },
          "scope": {
            "type": "string",
            "enum": [
              "runtime",
              "build",
              "both"
            ]
          }
        },
        "required": [
          "key",
          "value",
          "isSecret"
        ],
        "additionalProperties": false
      }
    },
    "envCategorizationEnabled": {
      "type": "boolean"
    },
    "forceRebuild": {
      "type": "boolean"
    },
    "process": {
      "type": "object",
      "properties": {
        "command": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "entrypoint": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "workingDir": {
          "type": "string"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "labels": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "resources": {
      "type": "object",
      "properties": {
        "cpu": {
          "type": "number"
        },
        "ram": {
          "type": "number"
        },
        "storage": {
          "type": "number"
        },
        "tier": {
          "type": "string"
        },
        "restartPolicy": {
          "type": "string"
        },
        "runtime": {
          "type": "object",
          "properties": {
            "autoSleep": {
              "type": "boolean"
            },
            "autoScale": {
              "type": "boolean"
            },
            "is24x7": {
              "type": "boolean"
            },
            "autoScaleMode": {
              "type": "string",
              "enum": [
                "vertical",
                "horizontal"
              ]
            },
            "autoScaleMaxCpu": {
              "type": "number"
            },
            "autoScaleMaxRam": {
              "type": "number"
            }
          },
          "required": [
            "autoSleep",
            "autoScale",
            "is24x7"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "cpu",
        "ram",
        "storage",
        "tier"
      ],
      "additionalProperties": false
    },
    "security": {
      "type": "object",
      "properties": {
        "dropCapabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "addCapabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "seccompProfile": {
          "type": "string"
        },
        "noNewPrivileges": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "healthcheck": {
      "type": "object",
      "properties": {
        "test": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "interval": {
          "type": "string"
        },
        "timeout": {
          "type": "string"
        },
        "startPeriod": {
          "type": "string"
        },
        "retries": {
          "type": "number"
        }
      },
      "required": [
        "test"
      ],
      "additionalProperties": false
    },
    "networking": {
      "type": "object",
      "properties": {
        "ports": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "protocol": {
                "type": "string",
                "enum": [
                  "http",
                  "tcp",
                  "udp"
                ]
              },
              "container": {
                "type": "number"
              },
              "tunnelUrl": {
                "type": "string"
              },
              "publicPort": {
                "type": "number"
              },
              "proxySiteId": {
                "type": "string"
              },
              "httpConfig": {
                "type": "object",
                "properties": {
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "extraConfig": {
                    "type": "string"
                  },
                  "proxySetHeader": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "cloudflareEnabled": {
                    "type": "boolean"
                  }
                },
                "required": [],
                "additionalProperties": false
              }
            },
            "required": [],
            "additionalProperties": false
          }
        },
        "internalNetworks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "networkName": {
                "type": "string"
              },
              "ipAddress": {
                "type": "string"
              },
              "gateway": {
                "type": "string"
              },
              "aliases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "networkName",
              "ipAddress",
              "gateway",
              "aliases"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [],
      "additionalProperties": false
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean"
            },
            "mode": {
              "type": "string",
              "enum": [
                "build",
                "restart",
                "swap"
              ]
            },
            "buildId": {
              "type": "string"
            }
          },
          "required": [
            "success"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "success": true,
        "mode": "build",
        "buildId": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTStart, stop, or restart a containerDetails +/api/v1/projects/:projectId/containers/:containerId/control

Transitions a container's runtime state via the requested action: start, stop, or restart.

  • Each action is only permitted from certain current states — for example, start requires the container be stopped, sleeping, or errored; stop requires running; restart requires running or sleeping.
  • Returns a state-conflict error if the container isn't in a valid state for the requested action.
  • Starting or restarting requires a positive account/organization balance and available free-tier compute allowance.
  • Requires container:control permission.
  • The container shows a "deploying" status during the transition, and reverts to its prior status if the action fails.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
actionrestart | start | stopYes
Complete request schema
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "restart",
        "start",
        "stop"
      ]
    }
  },
  "required": [
    "action"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "stopped",
                "running"
              ]
            }
          },
          "required": [
            "status"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "status": "stopped"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRun a one-off command inside a running containerDetails +/api/v1/projects/:projectId/containers/:containerId/exec

Executes a single command (as an argv array) inside the container and returns its exit code, stdout, and stderr once it completes or times out.

  • Execution is capped at 55 seconds.
  • Rate-limited to 30 attempts per minute per user, with a temporary block if exceeded.
  • The container must be running, the same requirement used for terminal sessions.
  • Commands are validated for argument count/length before being executed.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
commandstring[]Yes
timeoutMsnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "command": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "timeoutMs": {
      "type": "number"
    }
  },
  "required": [
    "command"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "exitCode": {
              "type": "number"
            },
            "stdout": {
              "type": "string"
            },
            "stderr": {
              "type": "string"
            }
          },
          "required": [
            "exitCode",
            "stdout",
            "stderr"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "exitCode": 0,
        "stdout": "string",
        "stderr": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETGet full configuration and status details for a containerDetails +/api/v1/projects/:projectId/containers/:containerId

Returns a container's complete stored configuration: resources, runtime, security, process, healthcheck, restart policy, labels, networking/ports, environment variable keys, attached volume mounts, and region info.

  • Environment variable values are not included; secret/scope flags are shown but not decrypted values.
  • Also reports the caller's effective permissions on the container (canControl, canUpdate, canDelete) based on their project role.
  • Requires container:logs permission.
  • Accessible while the project is hibernating.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "projectName": {
              "type": "string"
            },
            "region": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "location": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "location"
              ],
              "additionalProperties": false
            },
            "name": {
              "type": "string"
            },
            "kind": {
              "type": "string",
              "enum": [
                "service",
                "job"
              ]
            },
            "tier": {
              "type": "string",
              "enum": [
                "shared",
                "dedicated_sleepable",
                "dedicated_24x7",
                "auto_scaling",
                "docker-os"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "building",
                "stopped",
                "running",
                "deploying",
                "sleeping",
                "error",
                "deleting"
              ]
            },
            "source": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "git",
                    "docker",
                    "template"
                  ]
                },
                "template": {
                  "type": "string"
                },
                "gitRepository": {
                  "type": "string"
                },
                "dockerImage": {
                  "type": "string"
                },
                "branch": {
                  "type": "string"
                },
                "dockerfilePath": {
                  "type": "string"
                },
                "buildContext": {
                  "type": "string"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": false
            },
            "resources": {
              "type": "object",
              "properties": {
                "cpu": {
                  "type": "number"
                },
                "ram": {
                  "type": "number"
                },
                "storage": {
                  "type": "number"
                }
              },
              "required": [
                "cpu",
                "ram",
                "storage"
              ],
              "additionalProperties": false
            },
            "runtime": {
              "type": "object",
              "properties": {
                "autoSleep": {
                  "type": "boolean"
                },
                "autoScale": {
                  "type": "boolean"
                },
                "is24x7": {
                  "type": "boolean"
                },
                "autoScaleMode": {
                  "type": "string",
                  "enum": [
                    "vertical",
                    "horizontal"
                  ]
                },
                "autoScaleMaxCpu": {
                  "type": "number"
                },
                "autoScaleMaxRam": {
                  "type": "number"
                }
              },
              "required": [
                "autoSleep",
                "autoScale",
                "is24x7"
              ],
              "additionalProperties": false
            },
            "security": {
              "type": "object",
              "properties": {
                "dropCapabilities": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "addCapabilities": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "seccompProfile": {
                  "type": "string"
                },
                "noNewPrivileges": {
                  "type": "boolean"
                }
              },
              "required": [],
              "additionalProperties": false,
              "nullable": true
            },
            "process": {
              "type": "object",
              "properties": {
                "command": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "entrypoint": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "workingDir": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": false,
              "nullable": true
            },
            "healthcheck": {
              "type": "object",
              "properties": {
                "test": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "interval": {
                  "type": "string"
                },
                "timeout": {
                  "type": "string"
                },
                "startPeriod": {
                  "type": "string"
                },
                "retries": {
                  "type": "number"
                }
              },
              "required": [
                "test"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "restartPolicy": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "enum": [
                    "always",
                    "no",
                    "unless-stopped",
                    "on-failure"
                  ]
                },
                "maximumRetryCount": {
                  "type": "number"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "labels": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "networking": {
              "type": "object",
              "properties": {
                "ports": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "protocol": {
                        "type": "string",
                        "enum": [
                          "http",
                          "tcp",
                          "udp"
                        ]
                      },
                      "container": {
                        "type": "number"
                      },
                      "tunnelUrl": {
                        "type": "string"
                      },
                      "publicPort": {
                        "type": "number"
                      },
                      "proxySiteId": {
                        "type": "string"
                      },
                      "httpConfig": {
                        "type": "object",
                        "properties": {
                          "ssl": {
                            "type": "boolean"
                          },
                          "forceSsl": {
                            "type": "boolean"
                          },
                          "templates": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "extraConfig": {
                            "type": "string"
                          },
                          "proxySetHeader": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          },
                          "cloudflareEnabled": {
                            "type": "boolean"
                          }
                        },
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [],
                    "additionalProperties": false
                  }
                },
                "internalNetworks": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "networkName": {
                        "type": "string"
                      },
                      "ipAddress": {
                        "type": "string"
                      },
                      "gateway": {
                        "type": "string"
                      },
                      "aliases": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "networkName",
                      "ipAddress",
                      "gateway",
                      "aliases"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [],
              "additionalProperties": false
            },
            "primaryNetworkAlias": {
              "type": "string",
              "nullable": true
            },
            "environmentVariables": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  },
                  "isSecret": {
                    "type": "boolean"
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "runtime",
                      "build",
                      "both"
                    ]
                  }
                },
                "required": [
                  "key",
                  "isSecret"
                ],
                "additionalProperties": false
              }
            },
            "volumeMounts": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "volumeId": {
                    "type": "string"
                  },
                  "volumeName": {
                    "type": "string"
                  },
                  "dockerVolumeName": {
                    "type": "string"
                  },
                  "mountPoint": {
                    "type": "string"
                  },
                  "readOnly": {
                    "type": "boolean"
                  },
                  "sizeGb": {
                    "type": "string"
                  }
                },
                "required": [
                  "volumeId",
                  "volumeName",
                  "dockerVolumeName",
                  "mountPoint",
                  "readOnly",
                  "sizeGb"
                ],
                "additionalProperties": false
              }
            },
            "canControl": {
              "type": "boolean"
            },
            "canUpdate": {
              "type": "boolean"
            },
            "canDelete": {
              "type": "boolean"
            },
            "guardHold": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "scope": {
                  "type": "string",
                  "enum": [
                    "project",
                    "container"
                  ]
                },
                "containerId": {
                  "type": "string",
                  "nullable": true
                },
                "projectId": {
                  "type": "string"
                },
                "reasonCategory": {
                  "type": "string",
                  "enum": [
                    "cryptomining",
                    "proxy_abuse",
                    "network_abuse",
                    "reverse_shell",
                    "spam",
                    "malware",
                    "resource_abuse",
                    "crash_loop",
                    "policy",
                    "other"
                  ]
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "low",
                    "medium",
                    "high",
                    "critical"
                  ]
                },
                "summary": {
                  "type": "string"
                },
                "publicMessage": {
                  "type": "string",
                  "nullable": true
                },
                "placedAt": {
                  "type": "string"
                },
                "contact": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "scope",
                "containerId",
                "projectId",
                "reasonCategory",
                "severity",
                "summary",
                "publicMessage",
                "placedAt",
                "contact"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "createdAt": {
              "type": "string",
              "description": "Date string"
            },
            "updatedAt": {
              "type": "string",
              "description": "Date string"
            }
          },
          "required": [
            "id",
            "projectId",
            "projectName",
            "region",
            "name",
            "kind",
            "tier",
            "status",
            "source",
            "resources",
            "runtime",
            "security",
            "process",
            "healthcheck",
            "restartPolicy",
            "labels",
            "networking",
            "primaryNetworkAlias",
            "environmentVariables",
            "volumeMounts",
            "canControl",
            "canUpdate",
            "canDelete",
            "guardHold",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "id": "string",
        "projectId": "string",
        "projectName": "string",
        "region": {
          "id": "string",
          "name": "string",
          "location": "string"
        },
        "name": "string",
        "kind": "service",
        "tier": "shared",
        "status": "pending",
        "source": {
          "type": "git",
          "template": "string",
          "gitRepository": "string",
          "dockerImage": "string",
          "branch": "string",
          "dockerfilePath": "string",
          "buildContext": "string"
        },
        "resources": {
          "cpu": 0,
          "ram": 0,
          "storage": 0
        },
        "runtime": {
          "autoSleep": true,
          "autoScale": true,
          "is24x7": true,
          "autoScaleMode": "vertical",
          "autoScaleMaxCpu": 0,
          "autoScaleMaxRam": 0
        },
        "security": {
          "dropCapabilities": [
            "string"
          ],
          "addCapabilities": [
            "string"
          ],
          "seccompProfile": "string",
          "noNewPrivileges": true
        },
        "process": {
          "command": [
            "string"
          ],
          "entrypoint": [
            "string"
          ],
          "workingDir": "string"
        },
        "healthcheck": {
          "test": [
            "string"
          ],
          "interval": "string",
          "timeout": "string",
          "startPeriod": "string",
          "retries": 0
        },
        "restartPolicy": {
          "name": "always",
          "maximumRetryCount": 0
        },
        "labels": null,
        "networking": {
          "ports": [
            {
              "id": "string",
              "protocol": "http",
              "container": 0,
              "tunnelUrl": "string",
              "publicPort": 0,
              "proxySiteId": "string",
              "httpConfig": {
                "ssl": true,
                "forceSsl": true,
                "templates": [
                  "string"
                ],
                "extraConfig": "string",
                "proxySetHeader": null,
                "cloudflareEnabled": true
              }
            }
          ],
          "internalNetworks": [
            {
              "networkName": "string",
              "ipAddress": "string",
              "gateway": "string",
              "aliases": [
                "string"
              ]
            }
          ]
        },
        "primaryNetworkAlias": "string",
        "environmentVariables": [
          {
            "key": "string",
            "value": "string",
            "isSecret": true,
            "scope": "runtime"
          }
        ],
        "volumeMounts": [
          {
            "volumeId": "string",
            "volumeName": "string",
            "dockerVolumeName": "string",
            "mountPoint": "string",
            "readOnly": true,
            "sizeGb": "string"
          }
        ],
        "canControl": true,
        "canUpdate": true,
        "canDelete": true,
        "guardHold": {
          "id": "string",
          "scope": "project",
          "containerId": "string",
          "projectId": "string",
          "reasonCategory": "cryptomining",
          "severity": "low",
          "summary": "string",
          "publicMessage": "string",
          "placedAt": "string",
          "contact": "string"
        },
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETFetch recent stdout/stderr output from the container runtimeDetails +/api/v1/projects/:projectId/containers/:containerId/logs

Retrieves a snapshot of the container's current stdout and stderr output directly from the running container, rather than from persisted log history.

  • Only whatever output the runtime currently retains is returned.
  • The container must have been provisioned (have an active runtime); otherwise returns a 409.
  • Requires container:logs permission.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
tailBytesqueryNonumber—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "stdout": {
              "type": "string"
            },
            "stderr": {
              "type": "string"
            },
            "stdoutTruncated": {
              "type": "boolean"
            },
            "stderrTruncated": {
              "type": "boolean"
            },
            "tailBytes": {
              "type": "number"
            }
          },
          "required": [
            "stdout",
            "stderr",
            "stdoutTruncated",
            "stderrTruncated",
            "tailBytes"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "stdout": "string",
        "stderr": "string",
        "stdoutTruncated": true,
        "stderrTruncated": true,
        "tailBytes": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETGet current and historical CPU/memory/disk/network statsDetails +/api/v1/projects/:projectId/containers/:containerId/metrics

Returns the container's latest resource snapshot (CPU percent, memory usage/limit, storage usage, process count, network rx/tx) plus a time-series history over a configurable window, both reflecting live runtime state.

  • Callers can tune the history window length and maximum number of returned sample points via optional query parameters.
  • Requires container:logs permission.
  • Works while the project is hibernating.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
windowSecondsqueryNonumber—
maxPointsqueryNonumber—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "latest": {
              "type": "object",
              "properties": {
                "time": {
                  "type": "string"
                },
                "cpuPercent": {
                  "type": "number"
                },
                "memoryUsageBytes": {
                  "type": "number"
                },
                "memoryLimitBytes": {
                  "type": "number"
                },
                "memoryUsagePercent": {
                  "type": "number"
                },
                "storageUsedBytes": {
                  "type": "number"
                },
                "storageTotalBytes": {
                  "type": "number"
                },
                "storageUsagePercent": {
                  "type": "number"
                },
                "processes": {
                  "type": "number"
                },
                "networkRxBytes": {
                  "type": "number"
                },
                "networkTxBytes": {
                  "type": "number"
                }
              },
              "required": [
                "time",
                "cpuPercent",
                "memoryUsageBytes",
                "memoryLimitBytes",
                "memoryUsagePercent",
                "storageUsedBytes",
                "storageTotalBytes",
                "storageUsagePercent",
                "processes",
                "networkRxBytes",
                "networkTxBytes"
              ],
              "additionalProperties": false
            },
            "history": {
              "type": "object",
              "properties": {
                "windowSeconds": {
                  "type": "number"
                },
                "sampleIntervalSeconds": {
                  "type": "number"
                },
                "returnedPoints": {
                  "type": "number"
                },
                "records": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "time": {
                        "type": "string"
                      },
                      "cpuPercent": {
                        "type": "number"
                      },
                      "memoryUsageBytes": {
                        "type": "number"
                      },
                      "memoryLimitBytes": {
                        "type": "number"
                      },
                      "memoryUsagePercent": {
                        "type": "number"
                      },
                      "storageUsedBytes": {
                        "type": "number"
                      },
                      "storageTotalBytes": {
                        "type": "number"
                      },
                      "storageUsagePercent": {
                        "type": "number"
                      },
                      "processes": {
                        "type": "number"
                      },
                      "networkRxBytes": {
                        "type": "number"
                      },
                      "networkTxBytes": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "time",
                      "cpuPercent",
                      "memoryUsageBytes",
                      "memoryLimitBytes",
                      "memoryUsagePercent",
                      "storageUsedBytes",
                      "storageTotalBytes",
                      "storageUsagePercent",
                      "processes",
                      "networkRxBytes",
                      "networkTxBytes"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "windowSeconds",
                "sampleIntervalSeconds",
                "returnedPoints",
                "records"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "latest",
            "history"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "latest": {
          "time": "string",
          "cpuPercent": 0,
          "memoryUsageBytes": 0,
          "memoryLimitBytes": 0,
          "memoryUsagePercent": 0,
          "storageUsedBytes": 0,
          "storageTotalBytes": 0,
          "storageUsagePercent": 0,
          "processes": 0,
          "networkRxBytes": 0,
          "networkTxBytes": 0
        },
        "history": {
          "windowSeconds": 0,
          "sampleIntervalSeconds": 0,
          "returnedPoints": 0,
          "records": [
            {
              "time": "string",
              "cpuPercent": 0,
              "memoryUsageBytes": 0,
              "memoryLimitBytes": 0,
              "memoryUsagePercent": 0,
              "storageUsedBytes": 0,
              "storageTotalBytes": 0,
              "storageUsagePercent": 0,
              "processes": 0,
              "networkRxBytes": 0,
              "networkTxBytes": 0
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEPermanently delete a container and its runtimeDetails +/api/v1/projects/:projectId/containers/:containerId/remove

Deletes a container's runtime instance and permanently removes the container. This cannot be undone.

  • The container shows a "deleting" status during the operation to prevent concurrent delete requests.
  • If runtime deletion fails, the container is left in place and an error is returned instead of being removed.
  • Requires container:delete permission.
  • Allowed while the project is hibernating.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            },
            "projectId": {
              "type": "string"
            }
          },
          "required": [
            "success",
            "projectId"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "success": true,
        "projectId": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETGet suggested settings before replicating a containerDetails +/api/v1/projects/:projectId/containers/:containerId/replicate/context

Returns helper data for the replicate flow: the container's configured ports as suggested ports to expose on a replica, a default port choice, and details of any load-balancer group the container is already part of.

  • Group details include id, name, and algorithm, if the container has already been scaled.
  • Requires container:create permission, since replication effectively creates new containers.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "suggestedPorts": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "defaultPort": {
              "type": "number"
            },
            "existingLoadBalancerGroup": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "algorithm": {
                  "type": "string",
                  "enum": [
                    "round_robin",
                    "least_conn",
                    "ip_hash",
                    "weighted_round_robin",
                    "weighted_least_conn",
                    "weighted_ip_hash",
                    "random",
                    "weighted_random"
                  ]
                }
              },
              "required": [
                "id",
                "name",
                "algorithm"
              ],
              "additionalProperties": false,
              "nullable": true
            }
          },
          "required": [
            "suggestedPorts",
            "defaultPort",
            "existingLoadBalancerGroup"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "suggestedPorts": [
          0
        ],
        "defaultPort": 0,
        "existingLoadBalancerGroup": {
          "id": "string",
          "name": "string",
          "algorithm": "round_robin"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTClone a container, either standalone or into a scaled groupDetails +/api/v1/projects/:projectId/containers/:containerId/replicate

Creates one or more copies of an existing container's configuration, environment variables, and volume mounts.

  • In "independent" mode (the default), creates a single new standalone container with a generated unique name.
  • In "scale" mode, creates additional replicas and registers them, along with the original, under a load-balancer group using the requested algorithm (round-robin, least-connections, or IP-hash).
  • Scale mode optionally supports weighted traffic distribution across a specified replica count and port.
  • Requires container:create permission.
  • If replica creation fails partway through, any partially created replicas or group are automatically cleaned up.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
modescale | independentNo
scaleobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "scale",
        "independent"
      ]
    },
    "scale": {
      "type": "object",
      "properties": {
        "replicaCount": {
          "type": "number"
        },
        "port": {
          "type": "number"
        },
        "weights": {
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "algorithm": {
          "type": "string",
          "enum": [
            "round_robin",
            "least_conn",
            "ip_hash"
          ]
        },
        "internalReplicas": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "success": {
                  "const": true,
                  "type": "boolean"
                },
                "mode": {
                  "const": "independent",
                  "type": "string"
                },
                "newContainerId": {
                  "type": "string"
                }
              },
              "required": [
                "success",
                "mode",
                "newContainerId"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "success": {
                  "const": true,
                  "type": "boolean"
                },
                "mode": {
                  "const": "scale",
                  "type": "string"
                },
                "newContainerIds": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "loadBalancerGroupId": {
                  "type": "string"
                }
              },
              "required": [
                "success",
                "mode",
                "newContainerIds"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "success": {
                  "const": false,
                  "type": "boolean"
                },
                "error": {
                  "type": "string"
                }
              },
              "required": [
                "success",
                "error"
              ],
              "additionalProperties": false
            }
          ]
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": null,
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTPoll the live runtime for a container's real-time statusDetails +/api/v1/projects/:projectId/containers/:containerId/runtime

Inspects the container's actual current status, health, running image, start/finish timestamps, exit code, and network attachment details directly from the runtime, then updates the container's stored status to match.

  • If live inspection fails while the container is still "deploying" or "pending", returns the last known status with an "unknown" health instead of erroring.
  • Requires container:logs permission.
  • Works while the project is hibernating.
  • The container must already have a provisioned runtime.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "stopped",
                "running",
                "deploying",
                "sleeping",
                "error",
                "deleting"
              ]
            },
            "health": {
              "type": "string",
              "enum": [
                "unknown",
                "healthy",
                "starting",
                "unhealthy"
              ]
            },
            "actualImage": {
              "type": "string",
              "nullable": true
            },
            "startedAt": {
              "type": "string",
              "nullable": true
            },
            "finishedAt": {
              "type": "string",
              "nullable": true
            },
            "exitCode": {
              "type": "number",
              "nullable": true
            },
            "networking": {
              "type": "object",
              "properties": {
                "primaryNetworkName": {
                  "type": "string",
                  "nullable": true
                },
                "primaryInterfaceName": {
                  "type": "string",
                  "nullable": true
                },
                "primaryHostInterface": {
                  "type": "string",
                  "nullable": true
                },
                "primaryIp": {
                  "type": "string",
                  "nullable": true
                },
                "gatewayIp": {
                  "type": "string",
                  "nullable": true
                },
                "subnet": {
                  "type": "string",
                  "nullable": true
                },
                "ingressRateBps": {
                  "type": "number",
                  "nullable": true
                },
                "egressRateBps": {
                  "type": "number",
                  "nullable": true
                },
                "attachments": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "networkName": {
                        "type": "string",
                        "nullable": true
                      },
                      "interfaceName": {
                        "type": "string",
                        "nullable": true
                      },
                      "hostInterface": {
                        "type": "string",
                        "nullable": true
                      },
                      "ipAddress": {
                        "type": "string"
                      },
                      "gatewayIp": {
                        "type": "string",
                        "nullable": true
                      },
                      "subnet": {
                        "type": "string",
                        "nullable": true
                      },
                      "ingressRateBps": {
                        "type": "number",
                        "nullable": true
                      },
                      "egressRateBps": {
                        "type": "number",
                        "nullable": true
                      }
                    },
                    "required": [
                      "networkName",
                      "interfaceName",
                      "hostInterface",
                      "ipAddress",
                      "gatewayIp",
                      "subnet",
                      "ingressRateBps",
                      "egressRateBps"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "primaryNetworkName",
                "primaryInterfaceName",
                "primaryHostInterface",
                "primaryIp",
                "gatewayIp",
                "subnet",
                "ingressRateBps",
                "egressRateBps",
                "attachments"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "status",
            "health",
            "actualImage",
            "startedAt",
            "finishedAt",
            "exitCode"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "status": "pending",
        "health": "unknown",
        "actualImage": "string",
        "startedAt": "string",
        "finishedAt": "string",
        "exitCode": 0,
        "networking": {
          "primaryNetworkName": "string",
          "primaryInterfaceName": "string",
          "primaryHostInterface": "string",
          "primaryIp": "string",
          "gatewayIp": "string",
          "subnet": "string",
          "ingressRateBps": 0,
          "egressRateBps": 0,
          "attachments": [
            {
              "networkName": "string",
              "interfaceName": "string",
              "hostInterface": "string",
              "ipAddress": "string",
              "gatewayIp": "string",
              "subnet": "string",
              "ingressRateBps": 0,
              "egressRateBps": 0
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate a container sessionDetails +/api/v1/projects/:projectId/containers/:containerId/session

Creates a short-lived authenticated session for an interactive container operation.

  • Use the returned session details only for the requested container and discard them when the operation ends.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            },
            "url": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            }
          },
          "required": [
            "success",
            "url",
            "expiresAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "success": true,
        "url": "string",
        "expiresAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTOpen a new interactive terminal (shell) session for a containerDetails +/api/v1/projects/:projectId/containers/:containerId/terminal/session

Issues a short-lived, one-time connect token and a WebSocket URL for opening an interactive shell into a running container, defaulting to /bin/sh or a caller-specified absolute shell path.

  • The token expires in 60 seconds and must be claimed before then, at which point the session becomes active.
  • The container must be running at the time the token is claimed.
  • Returns a 503 if the terminal service isn't configured.
  • Rate-limited to 10 session creations per minute per user.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
shellstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "shell": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "sessionId": {
              "type": "string"
            },
            "connectToken": {
              "type": "string"
            },
            "connectUrl": {
              "type": "string"
            },
            "shell": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            }
          },
          "required": [
            "sessionId",
            "connectToken",
            "connectUrl",
            "shell",
            "expiresAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "sessionId": "string",
        "connectToken": "string",
        "connectUrl": "string",
        "shell": "string",
        "expiresAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top