Hubfly spaceDocs
Console

Cell API · Dashboard

Builds & Compose

Build from source, follow logs and retries, and deploy multi-container Compose stacks.

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 build or Compose deployment from the relevant source.
  2. Follow the build or deploy record and logs until it reaches a terminal state.
  3. Retry only after correcting source, credentials or runtime configuration.

List builds

curl
curl "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/builds" \
  -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 (20)

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/builds/createTrigger a new Git-based container build
GET/api/v1/projects/:projectId/buildsList and search a project's build history
DELETE/api/v1/projects/:projectId/builds/removePermanently delete finished build records
POST/api/v1/projects/:projectId/builds/:buildId/cancelCancel an in-progress build
GET/api/v1/projects/:projectId/builds/:buildId/draftRead a failed build's draft
GET/api/v1/projects/:projectId/builds/:buildIdGet full details for a single build
GET/api/v1/projects/:projectId/builds/:buildId/logsFetch a build's console output
POST/api/v1/projects/:projectId/builds/:buildId/retryResubmit a completed build as a new run
POST/api/v1/projects/:projectId/builds/:buildId/runtimeForce-refresh a build's status from the runtime
POST/api/v1/projects/:projectId/compose/deploy/createLaunch a Docker Compose stack deployment
GET/api/v1/projects/:projectId/compose/deploy/:deployIdPoll status and events for a compose deploy run
POST/api/v1/projects/:projectId/compose/git/branchesList branches for a Compose Git source
POST/api/v1/projects/:projectId/compose/git/detectDetect a Compose file in Git
POST/api/v1/projects/:projectId/compose/git/spec/createCreate a Compose spec from Git
GET/api/v1/projects/:projectId/compose/github/detectFind Docker Compose files in a GitHub repo
POST/api/v1/projects/:projectId/compose/github/spec/createImport and track a Compose spec from GitHub
POST/api/v1/projects/:projectId/compose/stacks/createSave a named Compose stack for reuse
GET/api/v1/projects/:projectId/compose/stacksList a user's saved Compose stacks
DELETE/api/v1/projects/:projectId/compose/stacks/:stackId/deleteDelete a saved Compose stack
GET/api/v1/projects/:projectId/compose/templatesBrowse built-in Compose stack templates
POSTTrigger a new Git-based container buildDetails +/api/v1/projects/:projectId/builds/create

Starts a new build from a Git repository (GitHub App-authenticated or self-hosted Git with a stored/derived access token), snapshotting the build config and environment variables at submission time.

  • The build is queued and runs asynchronously; the call returns as soon as it's accepted, and progress must be tracked via later status callbacks or polling.
  • Requires container:create permission on the project.
  • For self-hosted Git sources, a resolved access token may be saved to the project for reuse on future builds.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
sourceobjectYes
buildobjectYes
targetobjectYes
environmentVariablesobject[]No
draftFromBuildIdstringNo
timeoutSecondsnumberNo
resourceLimitsobjectNo
autoDeploybooleanNo
branchAutoDeploybooleanNo
isBranchContainerbooleanNo
baseBranchstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "source": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "github",
            "self_hosted"
          ]
        },
        "repository": {
          "type": "string"
        },
        "ref": {
          "type": "string"
        },
        "commitSha": {
          "type": "string"
        },
        "workingDir": {
          "type": "string"
        },
        "accessToken": {
          "type": "string"
        }
      },
      "required": [
        "provider",
        "repository"
      ],
      "additionalProperties": false
    },
    "build": {
      "type": "object",
      "properties": {
        "isAutoBuild": {
          "type": "boolean"
        },
        "runtime": {
          "type": "string",
          "enum": [
            "node",
            "bun",
            "python",
            "go",
            "java",
            "php",
            "static"
          ]
        },
        "framework": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "installCommand": {
          "type": "string"
        },
        "setupCommands": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "buildCommand": {
          "type": "string"
        },
        "postBuildCommands": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "runtimeInitCommand": {
          "type": "string"
        },
        "runCommand": {
          "type": "string"
        },
        "dockerfileContent": {
          "type": "string"
        },
        "autoDeploy": {
          "type": "boolean"
        },
        "branchAutoDeploy": {
          "type": "boolean"
        },
        "isBranchContainer": {
          "type": "boolean"
        },
        "baseBranch": {
          "type": "string"
        },
        "composeRunId": {
          "type": "string"
        },
        "composeContainerName": {
          "type": "string"
        }
      },
      "required": [
        "isAutoBuild",
        "runCommand"
      ],
      "additionalProperties": false
    },
    "target": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "containerId": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "service",
            "job"
          ]
        },
        "tier": {
          "type": "string",
          "enum": [
            "shared",
            "dedicated_sleepable",
            "dedicated_24x7",
            "auto_scaling",
            "docker-os"
          ]
        },
        "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
        },
        "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
        },
        "networkAliasId": {
          "type": "string"
        },
        "labels": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "ports": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "protocol": {
                "type": "string",
                "enum": [
                  "http",
                  "tcp",
                  "udp"
                ]
              },
              "container": {
                "type": "number"
              },
              "publicPort": {
                "type": "number"
              }
            },
            "required": [
              "protocol",
              "container"
            ],
            "additionalProperties": false
          }
        },
        "volumeMounts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "volumeId": {
                "type": "string"
              },
              "mountPoint": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              }
            },
            "required": [
              "volumeId",
              "mountPoint",
              "readOnly"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "name",
        "kind",
        "tier",
        "resources",
        "runtime",
        "restartPolicy",
        "labels",
        "ports",
        "volumeMounts"
      ],
      "additionalProperties": false
    },
    "environmentVariables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "isSecret": {
            "type": "boolean"
          },
          "scope": {
            "type": "string",
            "enum": [
              "runtime",
              "build",
              "both"
            ]
          },
          "reuseStoredValue": {
            "type": "boolean"
          }
        },
        "required": [
          "key",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "draftFromBuildId": {
      "type": "string"
    },
    "timeoutSeconds": {
      "type": "number"
    },
    "resourceLimits": {
      "type": "object",
      "properties": {
        "cpu": {
          "type": "number"
        },
        "memoryMb": {
          "type": "number"
        }
      },
      "required": [
        "cpu",
        "memoryMb"
      ],
      "additionalProperties": false
    },
    "autoDeploy": {
      "type": "boolean"
    },
    "branchAutoDeploy": {
      "type": "boolean"
    },
    "isBranchContainer": {
      "type": "boolean"
    },
    "baseBranch": {
      "type": "string"
    }
  },
  "required": [
    "source",
    "build",
    "target"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "building",
                "failed",
                "cancelled",
                "deploying",
                "success"
              ]
            }
          },
          "required": [
            "id",
            "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": {
        "id": "string",
        "status": "pending"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList and search a project's build historyDetails +/api/v1/projects/:projectId/builds

Returns a paginated, filterable list of build jobs for a project, supporting free-text search (matching build ID, commit SHA, ref, error message, or image tag) and filtering by build status.

  • The response includes aggregate summary counts (total/success/failed/active) and the average duration of completed builds.
  • The response includes a canDelete flag reflecting whether the caller holds delete permission.
  • Requires read access to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
pagequeryNonumber—
pageSizequeryNonumber—
queryqueryNostring—
statusqueryNostring—
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"
                  },
                  "sourceType": {
                    "type": "string",
                    "enum": [
                      "git",
                      "docker",
                      "template",
                      "cli",
                      "archive"
                    ]
                  },
                  "sourceInfo": {
                    "type": "object",
                    "properties": {
                      "ref": {
                        "type": "string"
                      },
                      "provider": {
                        "type": "string",
                        "enum": [
                          "github",
                          "self_hosted"
                        ]
                      },
                      "template": {
                        "type": "string"
                      },
                      "commitSha": {
                        "type": "string"
                      },
                      "dockerImage": {
                        "type": "string"
                      },
                      "archiveKey": {
                        "type": "string"
                      },
                      "archiveSha256": {
                        "type": "string"
                      },
                      "gitRepository": {
                        "type": "string"
                      },
                      "gitHost": {
                        "type": "string"
                      },
                      "workingDir": {
                        "type": "string"
                      },
                      "commitMessage": {
                        "type": "string"
                      },
                      "cliDeploy": {
                        "type": "object",
                        "properties": {
                          "builderVersion": {
                            "type": "string"
                          }
                        },
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [],
                    "additionalProperties": false
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "building",
                      "failed",
                      "cancelled",
                      "deploying",
                      "success"
                    ]
                  },
                  "imageTag": {
                    "type": "string",
                    "nullable": true
                  },
                  "commitSha": {
                    "type": "string",
                    "nullable": true
                  },
                  "ref": {
                    "type": "string",
                    "nullable": true
                  },
                  "durationMs": {
                    "type": "number",
                    "nullable": true
                  },
                  "error": {
                    "type": "string",
                    "nullable": true
                  },
                  "user": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "email": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "email"
                    ],
                    "additionalProperties": false
                  },
                  "startedAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "finishedAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  }
                },
                "required": [
                  "id",
                  "sourceType",
                  "sourceInfo",
                  "status",
                  "imageTag",
                  "commitSha",
                  "ref",
                  "durationMs",
                  "error",
                  "user",
                  "startedAt",
                  "finishedAt",
                  "createdAt"
                ],
                "additionalProperties": false
              }
            },
            "page": {
              "type": "number"
            },
            "pageSize": {
              "type": "number"
            },
            "total": {
              "type": "number"
            },
            "pageCount": {
              "type": "number"
            },
            "summary": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "number"
                },
                "success": {
                  "type": "number"
                },
                "failed": {
                  "type": "number"
                },
                "active": {
                  "type": "number"
                },
                "averageDurationMs": {
                  "type": "number",
                  "nullable": true
                }
              },
              "required": [
                "total",
                "success",
                "failed",
                "active",
                "averageDurationMs"
              ],
              "additionalProperties": false
            },
            "canDelete": {
              "type": "boolean"
            }
          },
          "required": [
            "items",
            "page",
            "pageSize",
            "total",
            "pageCount",
            "summary",
            "canDelete"
          ],
          "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",
            "sourceType": "git",
            "sourceInfo": {
              "ref": "string",
              "provider": "github",
              "template": "string",
              "commitSha": "string",
              "dockerImage": "string",
              "archiveKey": "string",
              "archiveSha256": "string",
              "gitRepository": "string",
              "gitHost": "string",
              "workingDir": "string",
              "commitMessage": "string",
              "cliDeploy": {
                "builderVersion": "string"
              }
            },
            "status": "pending",
            "imageTag": "string",
            "commitSha": "string",
            "ref": "string",
            "durationMs": 0,
            "error": "string",
            "user": {
              "id": "string",
              "name": "string",
              "email": "string"
            },
            "startedAt": "string",
            "finishedAt": "string",
            "createdAt": "string"
          }
        ],
        "page": 0,
        "pageSize": 0,
        "total": 0,
        "pageCount": 0,
        "summary": {
          "total": 0,
          "success": 0,
          "failed": 0,
          "active": 0,
          "averageDurationMs": 0
        },
        "canDelete": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEPermanently delete finished build recordsDetails +/api/v1/projects/:projectId/builds/remove

Deletes up to 50 build jobs at once from a project's history.

  • Only builds in a terminal state (success, failed, or cancelled) can be deleted; builds still in progress are left untouched.
  • Returns a conflict error if none of the selected builds qualify for deletion.
  • This action is irreversible.
  • Requires container:delete permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdsqueryYesarray—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deletedCount": {
              "type": "number"
            },
            "deletedIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "deletedCount",
            "deletedIds"
          ],
          "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": {
        "deletedCount": 0,
        "deletedIds": [
          "string"
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCancel an in-progress buildDetails +/api/v1/projects/:projectId/builds/:buildId/cancel

Cancels a currently pending, building, or deploying build job and stops the underlying build process.

  • Only succeeds if the build hasn't already started deployment and isn't already in a terminal state; otherwise returns a conflict error.
  • Requires container:control permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdpathYesstring—

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": {
              "const": "cancelled",
              "type": "string"
            }
          },
          "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": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETRead a failed build's draftDetails +/api/v1/projects/:projectId/builds/:buildId/draft

Return the form input of a failed or cancelled build of a new Git container (source, build settings, target, timeout and environment variables) so it can be corrected and submitted again. Variables inherited unchanged from the project environment are left out, and secret values are withheld (value: null, hasStoredValue: true).

  • Requires the container:create project permission.
  • Builds that are not failed or cancelled new-container Git builds return 409 BUILD_DRAFT_UNAVAILABLE; an unknown build returns 404 NOT_FOUND.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "buildId": {
              "type": "string"
            },
            "error": {
              "type": "string",
              "nullable": true
            },
            "deploymentError": {
              "type": "string",
              "nullable": true
            },
            "source": {
              "type": "object",
              "properties": {
                "provider": {
                  "type": "string",
                  "enum": [
                    "github",
                    "self_hosted"
                  ]
                },
                "repository": {
                  "type": "string"
                },
                "ref": {
                  "type": "string",
                  "nullable": true
                },
                "workingDir": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "provider",
                "repository",
                "ref",
                "workingDir"
              ],
              "additionalProperties": false
            },
            "build": {
              "type": "object",
              "properties": {
                "isAutoBuild": {
                  "type": "boolean"
                },
                "runtime": {
                  "type": "string",
                  "enum": [
                    "node",
                    "bun",
                    "python",
                    "go",
                    "java",
                    "php",
                    "static"
                  ]
                },
                "framework": {
                  "type": "string"
                },
                "version": {
                  "type": "string"
                },
                "installCommand": {
                  "type": "string"
                },
                "setupCommands": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "buildCommand": {
                  "type": "string"
                },
                "postBuildCommands": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "runtimeInitCommand": {
                  "type": "string"
                },
                "runCommand": {
                  "type": "string"
                },
                "dockerfileContent": {
                  "type": "string"
                },
                "isBranchContainer": {
                  "type": "boolean"
                },
                "baseBranch": {
                  "type": "string"
                },
                "composeRunId": {
                  "type": "string"
                },
                "composeContainerName": {
                  "type": "string"
                }
              },
              "required": [
                "isAutoBuild",
                "runCommand"
              ],
              "additionalProperties": false
            },
            "autoDeploy": {
              "type": "boolean"
            },
            "branchAutoDeploy": {
              "type": "boolean"
            },
            "target": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "containerId": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "service",
                    "job"
                  ]
                },
                "tier": {
                  "type": "string",
                  "enum": [
                    "shared",
                    "dedicated_sleepable",
                    "dedicated_24x7",
                    "auto_scaling",
                    "docker-os"
                  ]
                },
                "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
                },
                "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
                },
                "networkAliasId": {
                  "type": "string"
                },
                "labels": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                "ports": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "protocol": {
                        "type": "string",
                        "enum": [
                          "http",
                          "tcp",
                          "udp"
                        ]
                      },
                      "container": {
                        "type": "number"
                      },
                      "publicPort": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "protocol",
                      "container"
                    ],
                    "additionalProperties": false
                  }
                },
                "volumeMounts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "volumeId": {
                        "type": "string"
                      },
                      "mountPoint": {
                        "type": "string"
                      },
                      "readOnly": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "volumeId",
                      "mountPoint",
                      "readOnly"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "name",
                "kind",
                "tier",
                "resources",
                "runtime",
                "restartPolicy",
                "labels",
                "ports",
                "volumeMounts"
              ],
              "additionalProperties": false
            },
            "timeoutSeconds": {
              "type": "number"
            },
            "environmentVariables": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string",
                    "nullable": true
                  },
                  "isSecret": {
                    "type": "boolean"
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "runtime",
                      "build",
                      "both"
                    ]
                  },
                  "hasStoredValue": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "key",
                  "value",
                  "isSecret",
                  "scope",
                  "hasStoredValue"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "buildId",
            "error",
            "deploymentError",
            "source",
            "build",
            "autoDeploy",
            "branchAutoDeploy",
            "target",
            "timeoutSeconds",
            "environmentVariables"
          ],
          "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": {
        "buildId": "string",
        "error": "string",
        "deploymentError": "string",
        "source": {
          "provider": "github",
          "repository": "string",
          "ref": "string",
          "workingDir": "string"
        },
        "build": {
          "isAutoBuild": true,
          "runtime": "node",
          "framework": "string",
          "version": "string",
          "installCommand": "string",
          "setupCommands": [
            "string"
          ],
          "buildCommand": "string",
          "postBuildCommands": [
            "string"
          ],
          "runtimeInitCommand": "string",
          "runCommand": "string",
          "dockerfileContent": "string",
          "isBranchContainer": true,
          "baseBranch": "string",
          "composeRunId": "string",
          "composeContainerName": "string"
        },
        "autoDeploy": true,
        "branchAutoDeploy": true,
        "target": {
          "name": "string",
          "containerId": "string",
          "kind": "service",
          "tier": "shared",
          "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
          },
          "networkAliasId": "string",
          "labels": null,
          "ports": [
            {
              "id": "string",
              "protocol": "http",
              "container": 0,
              "publicPort": 0
            }
          ],
          "volumeMounts": [
            {
              "volumeId": "string",
              "mountPoint": "string",
              "readOnly": true
            }
          ]
        },
        "timeoutSeconds": 0,
        "environmentVariables": [
          {
            "key": "string",
            "value": "string",
            "isSecret": true,
            "scope": "runtime",
            "hasStoredValue": true
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETGet full details for a single buildDetails +/api/v1/projects/:projectId/builds/:buildId

Returns the full details for one build job, including its source info, build configuration, timing, resource limits, and any deployment/error details.

  • The response includes derived flags indicating whether the caller can retry (canRetry) or delete (canDelete) the build.
  • The response indicates whether logs are available for the build's source type.
  • Requires read access to the project.
  • Returns a 404 if the build does not belong to the given project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "nullable": true
            },
            "deploymentError": {
              "type": "string",
              "nullable": true
            },
            "sourceInfo": {
              "type": "object",
              "properties": {
                "ref": {
                  "type": "string"
                },
                "provider": {
                  "type": "string",
                  "enum": [
                    "github",
                    "self_hosted"
                  ]
                },
                "template": {
                  "type": "string"
                },
                "commitSha": {
                  "type": "string"
                },
                "dockerImage": {
                  "type": "string"
                },
                "archiveKey": {
                  "type": "string"
                },
                "archiveSha256": {
                  "type": "string"
                },
                "gitRepository": {
                  "type": "string"
                },
                "gitHost": {
                  "type": "string"
                },
                "workingDir": {
                  "type": "string"
                },
                "commitMessage": {
                  "type": "string"
                },
                "cliDeploy": {
                  "type": "object",
                  "properties": {
                    "builderVersion": {
                      "type": "string"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                }
              },
              "required": [],
              "additionalProperties": false
            },
            "canRetry": {
              "type": "boolean"
            },
            "canEditAndRetry": {
              "type": "boolean"
            },
            "canDelete": {
              "type": "boolean"
            },
            "logsAvailable": {
              "type": "boolean"
            },
            "id": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "sourceType": {
              "type": "string",
              "enum": [
                "git",
                "docker",
                "template",
                "cli",
                "archive"
              ]
            },
            "buildConfig": {
              "type": "object",
              "properties": {
                "build": {
                  "type": "object",
                  "properties": {
                    "isAutoBuild": {
                      "type": "boolean"
                    },
                    "runtime": {
                      "type": "string",
                      "enum": [
                        "node",
                        "bun",
                        "python",
                        "go",
                        "java",
                        "php",
                        "static"
                      ]
                    },
                    "framework": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "installCommand": {
                      "type": "string"
                    },
                    "setupCommands": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "buildCommand": {
                      "type": "string"
                    },
                    "postBuildCommands": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "runtimeInitCommand": {
                      "type": "string"
                    },
                    "runCommand": {
                      "type": "string"
                    },
                    "dockerfileContent": {
                      "type": "string"
                    },
                    "autoDeploy": {
                      "type": "boolean"
                    },
                    "branchAutoDeploy": {
                      "type": "boolean"
                    },
                    "isBranchContainer": {
                      "type": "boolean"
                    },
                    "baseBranch": {
                      "type": "string"
                    },
                    "composeRunId": {
                      "type": "string"
                    },
                    "composeContainerName": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "isAutoBuild",
                    "runCommand"
                  ],
                  "additionalProperties": false
                },
                "target": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "containerId": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "service",
                        "job"
                      ]
                    },
                    "tier": {
                      "type": "string",
                      "enum": [
                        "shared",
                        "dedicated_sleepable",
                        "dedicated_24x7",
                        "auto_scaling",
                        "docker-os"
                      ]
                    },
                    "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
                    },
                    "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
                    },
                    "networkAliasId": {
                      "type": "string"
                    },
                    "labels": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "ports": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "protocol": {
                            "type": "string",
                            "enum": [
                              "http",
                              "tcp",
                              "udp"
                            ]
                          },
                          "container": {
                            "type": "number"
                          },
                          "publicPort": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "protocol",
                          "container"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "volumeMounts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "volumeId": {
                            "type": "string"
                          },
                          "mountPoint": {
                            "type": "string"
                          },
                          "readOnly": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "volumeId",
                          "mountPoint",
                          "readOnly"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "name",
                    "kind",
                    "tier",
                    "resources",
                    "runtime",
                    "restartPolicy",
                    "labels",
                    "ports",
                    "volumeMounts"
                  ],
                  "additionalProperties": false
                },
                "environment": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": "string"
                      },
                      "isSecret": {
                        "type": "boolean"
                      },
                      "scope": {
                        "type": "string",
                        "enum": [
                          "runtime",
                          "build",
                          "both"
                        ]
                      }
                    },
                    "required": [
                      "key",
                      "isSecret",
                      "scope"
                    ],
                    "additionalProperties": false
                  }
                },
                "timeoutSeconds": {
                  "type": "number"
                },
                "resourceLimits": {
                  "type": "object",
                  "properties": {
                    "cpu": {
                      "type": "number"
                    },
                    "memoryMb": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "cpu",
                    "memoryMb"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "build",
                "target",
                "environment",
                "timeoutSeconds",
                "resourceLimits"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "building",
                "failed",
                "cancelled",
                "deploying",
                "success"
              ]
            },
            "imageTag": {
              "type": "string",
              "nullable": true
            },
            "commitSha": {
              "type": "string",
              "nullable": true
            },
            "ref": {
              "type": "string",
              "nullable": true
            },
            "startedAt": {
              "type": "string",
              "description": "Date string",
              "nullable": true
            },
            "finishedAt": {
              "type": "string",
              "description": "Date string",
              "nullable": true
            },
            "durationMs": {
              "type": "number",
              "nullable": true
            },
            "exitCode": {
              "type": "number",
              "nullable": true
            },
            "artifactUrl": {
              "type": "string",
              "nullable": true
            },
            "timeoutSeconds": {
              "type": "number",
              "nullable": true
            },
            "resourceLimits": {
              "type": "object",
              "properties": {
                "cpu": {
                  "type": "number"
                },
                "memoryMb": {
                  "type": "number"
                }
              },
              "required": [
                "cpu",
                "memoryMb"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "builderVersion": {
              "type": "string",
              "nullable": true
            },
            "retryOfBuildId": {
              "type": "string",
              "nullable": true
            },
            "containerId": {
              "type": "string",
              "nullable": true
            },
            "deploymentStartedAt": {
              "type": "string",
              "description": "Date string",
              "nullable": true
            },
            "deploymentFinishedAt": {
              "type": "string",
              "description": "Date string",
              "nullable": true
            },
            "createdAt": {
              "type": "string",
              "description": "Date string"
            },
            "updatedAt": {
              "type": "string",
              "description": "Date string"
            }
          },
          "required": [
            "error",
            "deploymentError",
            "sourceInfo",
            "canRetry",
            "canEditAndRetry",
            "canDelete",
            "logsAvailable",
            "id",
            "projectId",
            "sourceType",
            "buildConfig",
            "status",
            "imageTag",
            "commitSha",
            "ref",
            "startedAt",
            "finishedAt",
            "durationMs",
            "exitCode",
            "artifactUrl",
            "timeoutSeconds",
            "resourceLimits",
            "builderVersion",
            "retryOfBuildId",
            "containerId",
            "deploymentStartedAt",
            "deploymentFinishedAt",
            "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": {
        "error": "string",
        "deploymentError": "string",
        "sourceInfo": {
          "ref": "string",
          "provider": "github",
          "template": "string",
          "commitSha": "string",
          "dockerImage": "string",
          "archiveKey": "string",
          "archiveSha256": "string",
          "gitRepository": "string",
          "gitHost": "string",
          "workingDir": "string",
          "commitMessage": "string",
          "cliDeploy": {
            "builderVersion": "string"
          }
        },
        "canRetry": true,
        "canEditAndRetry": true,
        "canDelete": true,
        "logsAvailable": true,
        "id": "string",
        "projectId": "string",
        "sourceType": "git",
        "buildConfig": {
          "build": {
            "isAutoBuild": true,
            "runtime": "node",
            "framework": "string",
            "version": "string",
            "installCommand": "string",
            "setupCommands": [
              "string"
            ],
            "buildCommand": "string",
            "postBuildCommands": [
              "string"
            ],
            "runtimeInitCommand": "string",
            "runCommand": "string",
            "dockerfileContent": "string",
            "autoDeploy": true,
            "branchAutoDeploy": true,
            "isBranchContainer": true,
            "baseBranch": "string",
            "composeRunId": "string",
            "composeContainerName": "string"
          },
          "target": {
            "name": "string",
            "containerId": "string",
            "kind": "service",
            "tier": "shared",
            "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
            },
            "networkAliasId": "string",
            "labels": null,
            "ports": [
              {
                "id": "string",
                "protocol": "http",
                "container": 0,
                "publicPort": 0
              }
            ],
            "volumeMounts": [
              {
                "volumeId": "string",
                "mountPoint": "string",
                "readOnly": true
              }
            ]
          },
          "environment": [
            {
              "key": "string",
              "isSecret": true,
              "scope": "runtime"
            }
          ],
          "timeoutSeconds": 0,
          "resourceLimits": {
            "cpu": 0,
            "memoryMb": 0
          }
        },
        "status": "pending",
        "imageTag": "string",
        "commitSha": "string",
        "ref": "string",
        "startedAt": "string",
        "finishedAt": "string",
        "durationMs": 0,
        "exitCode": 0,
        "artifactUrl": "string",
        "timeoutSeconds": 0,
        "resourceLimits": {
          "cpu": 0,
          "memoryMb": 0
        },
        "builderVersion": "string",
        "retryOfBuildId": "string",
        "containerId": "string",
        "deploymentStartedAt": "string",
        "deploymentFinishedAt": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETFetch a build's console outputDetails +/api/v1/projects/:projectId/builds/:buildId/logs

Retrieves the build's console/log output, with an optional maximum byte limit.

  • Any values matching the project's secret environment variables are redacted before the text is returned.
  • Builds created locally via the CLI (hubfly deploy) have no remote logs and return a fixed explanatory message instead.
  • Requires read access to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdpathYesstring—
maxBytesqueryNonumber—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "logs": {
              "type": "string"
            },
            "truncated": {
              "type": "boolean"
            },
            "source": {
              "type": "string",
              "enum": [
                "runtime",
                "cli"
              ]
            },
            "redactedCount": {
              "type": "number"
            }
          },
          "required": [
            "logs",
            "truncated",
            "source",
            "redactedCount"
          ],
          "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": {
        "logs": "string",
        "truncated": true,
        "source": "runtime",
        "redactedCount": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTResubmit a completed build as a new runDetails +/api/v1/projects/:projectId/builds/:buildId/retry

Re-runs a previously completed build (success, failed, or cancelled) as a brand-new build job, linked back to the original via retryOfBuildId.

  • Copies the original build's Git source, build config, and environment variables into the new run.
  • Only builds with a retryable Git source snapshot can be retried.
  • An optional access token can be supplied for the retry; otherwise a stored self-hosted Git credential is used if available.
  • Like build creation, this queues an async build and returns once the submission is accepted.
  • Requires container:create permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
accessTokenstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "accessToken": {
      "type": "string"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "building",
                "failed",
                "cancelled",
                "deploying",
                "success"
              ]
            }
          },
          "required": [
            "id",
            "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": {
        "id": "string",
        "status": "pending"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTForce-refresh a build's status from the runtimeDetails +/api/v1/projects/:projectId/builds/:buildId/runtime

Fetches the current live status of a build and updates the stored build record to correct any drift from what actually happened.

  • Useful when a build appears stuck because a status update was missed.
  • Requires read access to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
buildIdpathYesstring—

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": {
            "buildId": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "building",
                "failed",
                "cancelled",
                "deploying",
                "success"
              ]
            },
            "imageTag": {
              "type": "string",
              "nullable": true
            },
            "commitSha": {
              "type": "string",
              "nullable": true
            },
            "ref": {
              "type": "string",
              "nullable": true
            },
            "startedAt": {
              "type": "string",
              "nullable": true
            },
            "finishedAt": {
              "type": "string",
              "nullable": true
            },
            "durationMs": {
              "type": "number",
              "nullable": true
            },
            "error": {
              "type": "string",
              "nullable": true
            },
            "exitCode": {
              "type": "number",
              "nullable": true
            },
            "artifactUrl": {
              "type": "string",
              "nullable": true
            },
            "builderVersion": {
              "type": "string",
              "nullable": true
            },
            "exposePort": {
              "type": "number",
              "nullable": true
            }
          },
          "required": [
            "buildId",
            "status",
            "imageTag",
            "commitSha",
            "ref",
            "startedAt",
            "finishedAt",
            "durationMs",
            "error",
            "exitCode",
            "artifactUrl",
            "builderVersion"
          ],
          "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": {
        "buildId": "string",
        "status": "pending",
        "imageTag": "string",
        "commitSha": "string",
        "ref": "string",
        "startedAt": "string",
        "finishedAt": "string",
        "durationMs": 0,
        "error": "string",
        "exitCode": 0,
        "artifactUrl": "string",
        "builderVersion": "string",
        "exposePort": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTLaunch a Docker Compose stack deploymentDetails +/api/v1/projects/:projectId/compose/deploy/create

Validates and normalizes a Compose spec and starts a new compose deploy run, building/starting each service's container in dependency-ordered stages and waiting on configurable health checks.

  • The deployment runs asynchronously; the endpoint returns immediately with a queued status, and progress and results must be polled separately.
  • Returns a 503 if the deployment cannot be queued, in which case the run is immediately marked failed.
  • Requires container:create permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
specobjectYes
healthobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "spec": {
      "type": "object",
      "properties": {
        "version": {
          "const": "1.0",
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "credentials": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "service": {
                "type": "string"
              },
              "username": {
                "type": "string"
              },
              "passwordSecret": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "service",
              "username",
              "passwordSecret"
            ],
            "additionalProperties": false
          }
        },
        "volumes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "sizeMB": {
                "type": "number"
              },
              "driver": {
                "type": "string"
              },
              "labels": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "required": [
              "id",
              "name",
              "sizeMB"
            ],
            "additionalProperties": false
          }
        },
        "containers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "source": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "docker",
                        "type": "string"
                      },
                      "image": {
                        "type": "string"
                      },
                      "registryAuth": {
                        "type": "object",
                        "properties": {
                          "registry": {
                            "type": "string"
                          },
                          "username": {
                            "type": "string"
                          },
                          "password": {
                            "type": "string"
                          }
                        },
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "type",
                      "image"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "template",
                        "type": "string"
                      },
                      "templateId": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "templateId"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "gitBuild",
                        "type": "string"
                      },
                      "provider": {
                        "type": "string",
                        "enum": [
                          "github",
                          "self_hosted"
                        ]
                      },
                      "repository": {
                        "type": "string"
                      },
                      "ref": {
                        "type": "string"
                      },
                      "commitSha": {
                        "type": "string"
                      },
                      "context": {
                        "type": "string"
                      },
                      "dockerfile": {
                        "type": "string"
                      },
                      "args": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "target": {
                        "type": "string"
                      },
                      "imageName": {
                        "type": "string"
                      },
                      "accessToken": {
                        "type": "string"
                      },
                      "autoDeploy": {
                        "type": "boolean"
                      },
                      "branchAutoDeploy": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "type",
                      "repository",
                      "ref",
                      "context",
                      "dockerfile"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "kind": {
                "type": "string",
                "enum": [
                  "service",
                  "job"
                ]
              },
              "stage": {
                "type": "number"
              },
              "dependsOn": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string"
                    },
                    "condition": {
                      "type": "string",
                      "enum": [
                        "service_started",
                        "service_healthy",
                        "service_completed_successfully"
                      ]
                    }
                  },
                  "required": [
                    "service"
                  ],
                  "additionalProperties": false
                }
              },
              "tier": {
                "type": "string",
                "enum": [
                  "shared",
                  "docker-os",
                  "dedicated",
                  "auto-scale"
                ]
              },
              "resources": {
                "type": "object",
                "properties": {
                  "cpu": {
                    "type": "number"
                  },
                  "ram": {
                    "type": "number"
                  },
                  "storage": {
                    "type": "number"
                  },
                  "maxCpu": {
                    "type": "number"
                  },
                  "maxRam": {
                    "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"
                    ]
                  }
                },
                "required": [
                  "autoSleep",
                  "autoScale",
                  "is24x7"
                ],
                "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
              },
              "publicEndpoint": {
                "type": "object",
                "properties": {
                  "port": {
                    "type": "number"
                  },
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "http",
                      "tcp",
                      "udp"
                    ]
                  },
                  "subdomain": {
                    "type": "string"
                  },
                  "httpConfig": {
                    "type": "object",
                    "properties": {
                      "ssl": {
                        "type": "boolean"
                      },
                      "forceSsl": {
                        "type": "boolean"
                      },
                      "templates": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "security-headers",
                            "basic-caching"
                          ]
                        }
                      },
                      "extraConfig": {
                        "type": "string"
                      },
                      "proxySetHeader": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "cloudflareEnabled": {
                        "type": "boolean"
                      }
                    },
                    "required": [],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "port"
                ],
                "additionalProperties": false
              },
              "restartPolicy": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "enum": [
                      "always",
                      "no",
                      "unless-stopped",
                      "on-failure"
                    ]
                  },
                  "maximumRetryCount": {
                    "type": "number"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "security": {
                "type": "object",
                "properties": {
                  "addCapabilities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "dropCapabilities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "networkAliases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "networkAliasId": {
                "type": "string"
              },
              "env": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    },
                    "secret": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "key",
                    "value"
                  ],
                  "additionalProperties": false
                }
              },
              "ports": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "container": {
                      "type": "number"
                    },
                    "protocol": {
                      "type": "string",
                      "enum": [
                        "TCP",
                        "UDP",
                        "HTTP"
                      ]
                    },
                    "host": {
                      "type": "number"
                    },
                    "hostIp": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "container",
                    "protocol"
                  ],
                  "additionalProperties": false
                }
              },
              "mounts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "volume": {
                      "type": "string"
                    },
                    "mountPath": {
                      "type": "string"
                    },
                    "readOnly": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "volume",
                    "mountPath"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "id",
              "name",
              "source",
              "kind",
              "stage",
              "dependsOn",
              "tier",
              "resources",
              "runtime",
              "process",
              "restartPolicy",
              "security",
              "networkAliases",
              "networkAliasId",
              "env",
              "ports",
              "mounts"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "version",
        "volumes",
        "containers"
      ],
      "additionalProperties": false
    },
    "health": {
      "type": "object",
      "properties": {
        "timeoutMs": {
          "type": "number"
        },
        "pollIntervalMs": {
          "type": "number"
        }
      },
      "required": [],
      "additionalProperties": false
    }
  },
  "required": [
    "spec"
  ],
  "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"
            },
            "deployId": {
              "type": "string"
            },
            "status": {
              "const": "queued",
              "type": "string"
            }
          },
          "required": [
            "success",
            "deployId",
            "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": {
        "success": true,
        "deployId": "string",
        "status": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETPoll status and events for a compose deploy runDetails +/api/v1/projects/:projectId/compose/deploy/:deployId

Returns the current status (queued/running/success/failed), the ordered list of progress events (per-step/per-container messages emitted during the deployment), any accumulated warnings, and the final result payload (per-service success/failure and build IDs) for a previously started compose deploy run.

  • Requires read access to the project.
  • Returns a 404 if the run doesn't belong to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
deployIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            },
            "status": {
              "type": "string",
              "enum": [
                "failed",
                "queued",
                "running",
                "success"
              ]
            },
            "warnings": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "events": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "failed",
                      "warning",
                      "running",
                      "success"
                    ]
                  },
                  "step": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "container": {
                    "type": "string"
                  },
                  "stage": {
                    "type": "number"
                  },
                  "timestamp": {
                    "type": "string"
                  }
                },
                "required": [
                  "status",
                  "step",
                  "message",
                  "timestamp"
                ],
                "additionalProperties": false
              }
            },
            "result": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean"
                },
                "error": {
                  "type": "string"
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "credentials": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "service": {
                        "type": "string"
                      },
                      "username": {
                        "type": "string"
                      },
                      "password": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "service",
                      "username",
                      "password"
                    ],
                    "additionalProperties": false
                  }
                },
                "results": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "stage": {
                        "type": "number"
                      },
                      "success": {
                        "type": "boolean"
                      },
                      "error": {
                        "type": "string"
                      },
                      "buildId": {
                        "type": "string"
                      },
                      "publicEndpoint": {
                        "type": "object",
                        "properties": {
                          "hostname": {
                            "type": "string"
                          },
                          "tunnelUrl": {
                            "type": "string",
                            "nullable": true
                          }
                        },
                        "required": [
                          "hostname",
                          "tunnelUrl"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "name",
                      "stage",
                      "success"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "success"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "startedAt": {
              "type": "string",
              "nullable": true
            },
            "finishedAt": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "success",
            "status",
            "warnings",
            "events",
            "result",
            "startedAt",
            "finishedAt"
          ],
          "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,
        "status": "failed",
        "warnings": [
          "string"
        ],
        "events": [
          {
            "status": "failed",
            "step": "string",
            "message": "string",
            "container": "string",
            "stage": 0,
            "timestamp": "string"
          }
        ],
        "result": {
          "success": true,
          "error": "string",
          "warnings": [
            "string"
          ],
          "credentials": [
            {
              "name": "string",
              "service": "string",
              "username": "string",
              "password": "string"
            }
          ],
          "results": [
            {
              "name": "string",
              "stage": 0,
              "success": true,
              "error": "string",
              "buildId": "string",
              "publicEndpoint": {
                "hostname": "string",
                "tunnelUrl": "string"
              }
            }
          ]
        },
        "startedAt": "string",
        "finishedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTList branches for a Compose Git sourceDetails +/api/v1/projects/:projectId/compose/git/branches

Loads branches from a configured Git repository so a Compose source can target a specific ref.

  • Requires project access and a repository source in the request.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
repositorystringYes
accessTokenstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string"
    },
    "accessToken": {
      "type": "string"
    }
  },
  "required": [
    "repository"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "branches": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "defaultBranch": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "branches",
            "defaultBranch"
          ],
          "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": {
        "branches": [
          "string"
        ],
        "defaultBranch": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTDetect a Compose file in GitDetails +/api/v1/projects/:projectId/compose/git/detect

Inspects a Git repository and identifies Compose files, services and parsing warnings before import.

  • Warnings are returned for unsupported Compose syntax instead of silently treating it as supported.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
repositorystringYes
branchstringNo
rootDirstringNo
accessTokenstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "rootDir": {
      "type": "string"
    },
    "accessToken": {
      "type": "string"
    }
  },
  "required": [
    "repository"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "files": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "defaultFile": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "files",
            "defaultFile"
          ],
          "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": {
        "files": [
          "string"
        ],
        "defaultFile": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate a Compose spec from GitDetails +/api/v1/projects/:projectId/compose/git/spec/create

Fetches and parses a selected Git repository ref into a Hubfly space ComposeSpec ready for review or deployment.

  • Review returned warnings and the generated spec before starting a stack deployment.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
repositorystringYes
branchstringYes
rootDirstringNo
composeFilePathstringYes
accessTokenstringNo
deployTriggerpush | ciNo
autoDeployEnabledbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "rootDir": {
      "type": "string"
    },
    "composeFilePath": {
      "type": "string"
    },
    "accessToken": {
      "type": "string"
    },
    "deployTrigger": {
      "type": "string",
      "enum": [
        "push",
        "ci"
      ]
    },
    "autoDeployEnabled": {
      "type": "boolean"
    }
  },
  "required": [
    "repository",
    "branch",
    "composeFilePath"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "spec": {
              "type": "object",
              "properties": {
                "version": {
                  "const": "1.0",
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "credentials": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "service": {
                        "type": "string"
                      },
                      "username": {
                        "type": "string"
                      },
                      "passwordSecret": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "service",
                      "username",
                      "passwordSecret"
                    ],
                    "additionalProperties": false
                  }
                },
                "volumes": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "sizeMB": {
                        "type": "number"
                      },
                      "driver": {
                        "type": "string"
                      },
                      "labels": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "sizeMB"
                    ],
                    "additionalProperties": false
                  }
                },
                "containers": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "source": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "const": "docker",
                                "type": "string"
                              },
                              "image": {
                                "type": "string"
                              },
                              "registryAuth": {
                                "type": "object",
                                "properties": {
                                  "registry": {
                                    "type": "string"
                                  },
                                  "username": {
                                    "type": "string"
                                  },
                                  "password": {
                                    "type": "string"
                                  }
                                },
                                "required": [],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "type",
                              "image"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "const": "template",
                                "type": "string"
                              },
                              "templateId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "type",
                              "templateId"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "const": "gitBuild",
                                "type": "string"
                              },
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "github",
                                  "self_hosted"
                                ]
                              },
                              "repository": {
                                "type": "string"
                              },
                              "ref": {
                                "type": "string"
                              },
                              "commitSha": {
                                "type": "string"
                              },
                              "context": {
                                "type": "string"
                              },
                              "dockerfile": {
                                "type": "string"
                              },
                              "args": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "target": {
                                "type": "string"
                              },
                              "imageName": {
                                "type": "string"
                              },
                              "accessToken": {
                                "type": "string"
                              },
                              "autoDeploy": {
                                "type": "boolean"
                              },
                              "branchAutoDeploy": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "type",
                              "repository",
                              "ref",
                              "context",
                              "dockerfile"
                            ],
                            "additionalProperties": false
                          }
                        ]
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "service",
                          "job"
                        ]
                      },
                      "stage": {
                        "type": "number"
                      },
                      "dependsOn": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "service": {
                              "type": "string"
                            },
                            "condition": {
                              "type": "string",
                              "enum": [
                                "service_started",
                                "service_healthy",
                                "service_completed_successfully"
                              ]
                            }
                          },
                          "required": [
                            "service"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "tier": {
                        "type": "string",
                        "enum": [
                          "shared",
                          "docker-os",
                          "dedicated",
                          "auto-scale"
                        ]
                      },
                      "resources": {
                        "type": "object",
                        "properties": {
                          "cpu": {
                            "type": "number"
                          },
                          "ram": {
                            "type": "number"
                          },
                          "storage": {
                            "type": "number"
                          },
                          "maxCpu": {
                            "type": "number"
                          },
                          "maxRam": {
                            "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"
                            ]
                          }
                        },
                        "required": [
                          "autoSleep",
                          "autoScale",
                          "is24x7"
                        ],
                        "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
                      },
                      "publicEndpoint": {
                        "type": "object",
                        "properties": {
                          "port": {
                            "type": "number"
                          },
                          "protocol": {
                            "type": "string",
                            "enum": [
                              "http",
                              "tcp",
                              "udp"
                            ]
                          },
                          "subdomain": {
                            "type": "string"
                          },
                          "httpConfig": {
                            "type": "object",
                            "properties": {
                              "ssl": {
                                "type": "boolean"
                              },
                              "forceSsl": {
                                "type": "boolean"
                              },
                              "templates": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "enum": [
                                    "security-headers",
                                    "basic-caching"
                                  ]
                                }
                              },
                              "extraConfig": {
                                "type": "string"
                              },
                              "proxySetHeader": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "cloudflareEnabled": {
                                "type": "boolean"
                              }
                            },
                            "required": [],
                            "additionalProperties": false
                          }
                        },
                        "required": [
                          "port"
                        ],
                        "additionalProperties": false
                      },
                      "restartPolicy": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "enum": [
                              "always",
                              "no",
                              "unless-stopped",
                              "on-failure"
                            ]
                          },
                          "maximumRetryCount": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "name"
                        ],
                        "additionalProperties": false
                      },
                      "security": {
                        "type": "object",
                        "properties": {
                          "addCapabilities": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "dropCapabilities": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [],
                        "additionalProperties": false
                      },
                      "networkAliases": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "networkAliasId": {
                        "type": "string"
                      },
                      "env": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "key": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            },
                            "secret": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "key",
                            "value"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "ports": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "container": {
                              "type": "number"
                            },
                            "protocol": {
                              "type": "string",
                              "enum": [
                                "TCP",
                                "UDP",
                                "HTTP"
                              ]
                            },
                            "host": {
                              "type": "number"
                            },
                            "hostIp": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "container",
                            "protocol"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "mounts": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "volume": {
                              "type": "string"
                            },
                            "mountPath": {
                              "type": "string"
                            },
                            "readOnly": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "volume",
                            "mountPath"
                          ],
                          "additionalProperties": false
                        }
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "source",
                      "kind",
                      "stage",
                      "dependsOn",
                      "tier",
                      "resources",
                      "runtime",
                      "process",
                      "restartPolicy",
                      "security",
                      "networkAliases",
                      "networkAliasId",
                      "env",
                      "ports",
                      "mounts"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "version",
                "volumes",
                "containers"
              ],
              "additionalProperties": false
            },
            "warnings": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "repository": {
              "type": "string"
            },
            "commitSha": {
              "type": "string"
            }
          },
          "required": [
            "spec",
            "warnings",
            "repository",
            "commitSha"
          ],
          "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": {
        "spec": {
          "version": "string",
          "name": "string",
          "description": "string",
          "credentials": [
            {
              "name": "string",
              "service": "string",
              "username": "string",
              "passwordSecret": "string"
            }
          ],
          "volumes": [
            {
              "id": "string",
              "name": "string",
              "sizeMB": 0,
              "driver": "string",
              "labels": null
            }
          ],
          "containers": [
            {
              "id": "string",
              "name": "string",
              "source": null,
              "kind": "service",
              "stage": 0,
              "dependsOn": [
                {
                  "service": "string",
                  "condition": "service_started"
                }
              ],
              "tier": "shared",
              "resources": {
                "cpu": 0,
                "ram": 0,
                "storage": 0,
                "maxCpu": 0,
                "maxRam": 0
              },
              "runtime": {
                "autoSleep": true,
                "autoScale": true,
                "is24x7": true,
                "autoScaleMode": "vertical"
              },
              "process": {
                "command": [
                  "string"
                ],
                "entrypoint": [
                  "string"
                ],
                "workingDir": "string"
              },
              "healthcheck": {
                "test": [
                  "string"
                ],
                "interval": "string",
                "timeout": "string",
                "startPeriod": "string",
                "retries": 0
              },
              "publicEndpoint": {
                "port": 0,
                "protocol": "http",
                "subdomain": "string",
                "httpConfig": {
                  "ssl": true,
                  "forceSsl": true,
                  "templates": [
                    "security-headers"
                  ],
                  "extraConfig": "string",
                  "proxySetHeader": null,
                  "cloudflareEnabled": true
                }
              },
              "restartPolicy": {
                "name": "always",
                "maximumRetryCount": 0
              },
              "security": {
                "addCapabilities": [
                  "string"
                ],
                "dropCapabilities": [
                  "string"
                ]
              },
              "networkAliases": [
                "string"
              ],
              "networkAliasId": "string",
              "env": [
                {
                  "key": "string",
                  "value": "string",
                  "secret": true
                }
              ],
              "ports": [
                {
                  "container": 0,
                  "protocol": "TCP",
                  "host": 0,
                  "hostIp": "string"
                }
              ],
              "mounts": [
                {
                  "volume": "string",
                  "mountPath": "string",
                  "readOnly": true
                }
              ]
            }
          ]
        },
        "warnings": [
          "string"
        ],
        "repository": "string",
        "commitSha": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETFind Docker Compose files in a GitHub repoDetails +/api/v1/projects/:projectId/compose/github/detect

Lists candidate Docker Compose file paths (docker-compose.yml/yaml, compose.yml/yaml) found anywhere in a GitHub repository branch's file tree, optionally scoped to a root directory.

  • Picks a sensible default file (preferring a top-level/root docker-compose.yml(.yaml), otherwise the shallowest match) and returns it alongside the full filtered list.
  • Does not parse or validate the file contents.
  • Requires an authenticated user and a verified GitHub App installation for the target repository.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
repositoryqueryYesstring—
branchqueryNostring—
rootDirqueryNostring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "files": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "defaultFile": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "files",
            "defaultFile"
          ],
          "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": {
        "files": [
          "string"
        ],
        "defaultFile": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTImport and track a Compose spec from GitHubDetails +/api/v1/projects/:projectId/compose/github/spec/create

Fetches a specific Docker Compose file's contents from a GitHub repository/branch, parses it into a normalized Compose spec, and resolves the branch's latest commit SHA.

  • Creates or updates a tracked "GitHub compose stack" (keyed by project + repository + branch + file path) storing the parsed spec, auto-deploy setting, and deploy trigger (push or CI) for future automated deployments.
  • Requires read access to the project.
  • Any parsing warnings are returned alongside the resulting spec.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
repositorystringYes
branchstringYes
rootDirstringNo
composeFilePathstringYes
deployTriggerpush | ciNo
autoDeployEnabledbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "rootDir": {
      "type": "string"
    },
    "composeFilePath": {
      "type": "string"
    },
    "deployTrigger": {
      "type": "string",
      "enum": [
        "push",
        "ci"
      ]
    },
    "autoDeployEnabled": {
      "type": "boolean"
    }
  },
  "required": [
    "repository",
    "branch",
    "composeFilePath"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "spec": {
              "type": "object",
              "properties": {
                "version": {
                  "const": "1.0",
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "credentials": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "service": {
                        "type": "string"
                      },
                      "username": {
                        "type": "string"
                      },
                      "passwordSecret": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "service",
                      "username",
                      "passwordSecret"
                    ],
                    "additionalProperties": false
                  }
                },
                "volumes": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "sizeMB": {
                        "type": "number"
                      },
                      "driver": {
                        "type": "string"
                      },
                      "labels": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "sizeMB"
                    ],
                    "additionalProperties": false
                  }
                },
                "containers": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "source": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "const": "docker",
                                "type": "string"
                              },
                              "image": {
                                "type": "string"
                              },
                              "registryAuth": {
                                "type": "object",
                                "properties": {
                                  "registry": {
                                    "type": "string"
                                  },
                                  "username": {
                                    "type": "string"
                                  },
                                  "password": {
                                    "type": "string"
                                  }
                                },
                                "required": [],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "type",
                              "image"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "const": "template",
                                "type": "string"
                              },
                              "templateId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "type",
                              "templateId"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "const": "gitBuild",
                                "type": "string"
                              },
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "github",
                                  "self_hosted"
                                ]
                              },
                              "repository": {
                                "type": "string"
                              },
                              "ref": {
                                "type": "string"
                              },
                              "commitSha": {
                                "type": "string"
                              },
                              "context": {
                                "type": "string"
                              },
                              "dockerfile": {
                                "type": "string"
                              },
                              "args": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "target": {
                                "type": "string"
                              },
                              "imageName": {
                                "type": "string"
                              },
                              "accessToken": {
                                "type": "string"
                              },
                              "autoDeploy": {
                                "type": "boolean"
                              },
                              "branchAutoDeploy": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "type",
                              "repository",
                              "ref",
                              "context",
                              "dockerfile"
                            ],
                            "additionalProperties": false
                          }
                        ]
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "service",
                          "job"
                        ]
                      },
                      "stage": {
                        "type": "number"
                      },
                      "dependsOn": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "service": {
                              "type": "string"
                            },
                            "condition": {
                              "type": "string",
                              "enum": [
                                "service_started",
                                "service_healthy",
                                "service_completed_successfully"
                              ]
                            }
                          },
                          "required": [
                            "service"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "tier": {
                        "type": "string",
                        "enum": [
                          "shared",
                          "docker-os",
                          "dedicated",
                          "auto-scale"
                        ]
                      },
                      "resources": {
                        "type": "object",
                        "properties": {
                          "cpu": {
                            "type": "number"
                          },
                          "ram": {
                            "type": "number"
                          },
                          "storage": {
                            "type": "number"
                          },
                          "maxCpu": {
                            "type": "number"
                          },
                          "maxRam": {
                            "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"
                            ]
                          }
                        },
                        "required": [
                          "autoSleep",
                          "autoScale",
                          "is24x7"
                        ],
                        "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
                      },
                      "publicEndpoint": {
                        "type": "object",
                        "properties": {
                          "port": {
                            "type": "number"
                          },
                          "protocol": {
                            "type": "string",
                            "enum": [
                              "http",
                              "tcp",
                              "udp"
                            ]
                          },
                          "subdomain": {
                            "type": "string"
                          },
                          "httpConfig": {
                            "type": "object",
                            "properties": {
                              "ssl": {
                                "type": "boolean"
                              },
                              "forceSsl": {
                                "type": "boolean"
                              },
                              "templates": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "enum": [
                                    "security-headers",
                                    "basic-caching"
                                  ]
                                }
                              },
                              "extraConfig": {
                                "type": "string"
                              },
                              "proxySetHeader": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "cloudflareEnabled": {
                                "type": "boolean"
                              }
                            },
                            "required": [],
                            "additionalProperties": false
                          }
                        },
                        "required": [
                          "port"
                        ],
                        "additionalProperties": false
                      },
                      "restartPolicy": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "enum": [
                              "always",
                              "no",
                              "unless-stopped",
                              "on-failure"
                            ]
                          },
                          "maximumRetryCount": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "name"
                        ],
                        "additionalProperties": false
                      },
                      "security": {
                        "type": "object",
                        "properties": {
                          "addCapabilities": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "dropCapabilities": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [],
                        "additionalProperties": false
                      },
                      "networkAliases": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "networkAliasId": {
                        "type": "string"
                      },
                      "env": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "key": {
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            },
                            "secret": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "key",
                            "value"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "ports": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "container": {
                              "type": "number"
                            },
                            "protocol": {
                              "type": "string",
                              "enum": [
                                "TCP",
                                "UDP",
                                "HTTP"
                              ]
                            },
                            "host": {
                              "type": "number"
                            },
                            "hostIp": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "container",
                            "protocol"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "mounts": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "volume": {
                              "type": "string"
                            },
                            "mountPath": {
                              "type": "string"
                            },
                            "readOnly": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "volume",
                            "mountPath"
                          ],
                          "additionalProperties": false
                        }
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "source",
                      "kind",
                      "stage",
                      "dependsOn",
                      "tier",
                      "resources",
                      "runtime",
                      "process",
                      "restartPolicy",
                      "security",
                      "networkAliases",
                      "networkAliasId",
                      "env",
                      "ports",
                      "mounts"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "version",
                "volumes",
                "containers"
              ],
              "additionalProperties": false
            },
            "warnings": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "repository": {
              "type": "string"
            },
            "commitSha": {
              "type": "string"
            }
          },
          "required": [
            "spec",
            "warnings",
            "repository",
            "commitSha"
          ],
          "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": {
        "spec": {
          "version": "string",
          "name": "string",
          "description": "string",
          "credentials": [
            {
              "name": "string",
              "service": "string",
              "username": "string",
              "passwordSecret": "string"
            }
          ],
          "volumes": [
            {
              "id": "string",
              "name": "string",
              "sizeMB": 0,
              "driver": "string",
              "labels": null
            }
          ],
          "containers": [
            {
              "id": "string",
              "name": "string",
              "source": null,
              "kind": "service",
              "stage": 0,
              "dependsOn": [
                {
                  "service": "string",
                  "condition": "service_started"
                }
              ],
              "tier": "shared",
              "resources": {
                "cpu": 0,
                "ram": 0,
                "storage": 0,
                "maxCpu": 0,
                "maxRam": 0
              },
              "runtime": {
                "autoSleep": true,
                "autoScale": true,
                "is24x7": true,
                "autoScaleMode": "vertical"
              },
              "process": {
                "command": [
                  "string"
                ],
                "entrypoint": [
                  "string"
                ],
                "workingDir": "string"
              },
              "healthcheck": {
                "test": [
                  "string"
                ],
                "interval": "string",
                "timeout": "string",
                "startPeriod": "string",
                "retries": 0
              },
              "publicEndpoint": {
                "port": 0,
                "protocol": "http",
                "subdomain": "string",
                "httpConfig": {
                  "ssl": true,
                  "forceSsl": true,
                  "templates": [
                    "security-headers"
                  ],
                  "extraConfig": "string",
                  "proxySetHeader": null,
                  "cloudflareEnabled": true
                }
              },
              "restartPolicy": {
                "name": "always",
                "maximumRetryCount": 0
              },
              "security": {
                "addCapabilities": [
                  "string"
                ],
                "dropCapabilities": [
                  "string"
                ]
              },
              "networkAliases": [
                "string"
              ],
              "networkAliasId": "string",
              "env": [
                {
                  "key": "string",
                  "value": "string",
                  "secret": true
                }
              ],
              "ports": [
                {
                  "container": 0,
                  "protocol": "TCP",
                  "host": 0,
                  "hostIp": "string"
                }
              ],
              "mounts": [
                {
                  "volume": "string",
                  "mountPath": "string",
                  "readOnly": true
                }
              ]
            }
          ]
        },
        "warnings": [
          "string"
        ],
        "repository": "string",
        "commitSha": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTSave a named Compose stack for reuseDetails +/api/v1/projects/:projectId/compose/stacks/create

Validates a Compose spec and saves it as a named, reusable stack scoped to the current user and project.

  • If a saved stack with the same name already exists for that user/project, its spec is overwritten rather than creating a duplicate; the response's updated flag indicates which occurred.
  • This only persists the spec definition and does not trigger a deployment.
  • Requires read access to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
specobjectYes
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "spec": {
      "type": "object",
      "properties": {
        "version": {
          "const": "1.0",
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "credentials": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "service": {
                "type": "string"
              },
              "username": {
                "type": "string"
              },
              "passwordSecret": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "service",
              "username",
              "passwordSecret"
            ],
            "additionalProperties": false
          }
        },
        "volumes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "sizeMB": {
                "type": "number"
              },
              "driver": {
                "type": "string"
              },
              "labels": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            },
            "required": [
              "id",
              "name",
              "sizeMB"
            ],
            "additionalProperties": false
          }
        },
        "containers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "source": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "docker",
                        "type": "string"
                      },
                      "image": {
                        "type": "string"
                      },
                      "registryAuth": {
                        "type": "object",
                        "properties": {
                          "registry": {
                            "type": "string"
                          },
                          "username": {
                            "type": "string"
                          },
                          "password": {
                            "type": "string"
                          }
                        },
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "type",
                      "image"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "template",
                        "type": "string"
                      },
                      "templateId": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "templateId"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "gitBuild",
                        "type": "string"
                      },
                      "provider": {
                        "type": "string",
                        "enum": [
                          "github",
                          "self_hosted"
                        ]
                      },
                      "repository": {
                        "type": "string"
                      },
                      "ref": {
                        "type": "string"
                      },
                      "commitSha": {
                        "type": "string"
                      },
                      "context": {
                        "type": "string"
                      },
                      "dockerfile": {
                        "type": "string"
                      },
                      "args": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "target": {
                        "type": "string"
                      },
                      "imageName": {
                        "type": "string"
                      },
                      "accessToken": {
                        "type": "string"
                      },
                      "autoDeploy": {
                        "type": "boolean"
                      },
                      "branchAutoDeploy": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "type",
                      "repository",
                      "ref",
                      "context",
                      "dockerfile"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "kind": {
                "type": "string",
                "enum": [
                  "service",
                  "job"
                ]
              },
              "stage": {
                "type": "number"
              },
              "dependsOn": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string"
                    },
                    "condition": {
                      "type": "string",
                      "enum": [
                        "service_started",
                        "service_healthy",
                        "service_completed_successfully"
                      ]
                    }
                  },
                  "required": [
                    "service"
                  ],
                  "additionalProperties": false
                }
              },
              "tier": {
                "type": "string",
                "enum": [
                  "shared",
                  "docker-os",
                  "dedicated",
                  "auto-scale"
                ]
              },
              "resources": {
                "type": "object",
                "properties": {
                  "cpu": {
                    "type": "number"
                  },
                  "ram": {
                    "type": "number"
                  },
                  "storage": {
                    "type": "number"
                  },
                  "maxCpu": {
                    "type": "number"
                  },
                  "maxRam": {
                    "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"
                    ]
                  }
                },
                "required": [
                  "autoSleep",
                  "autoScale",
                  "is24x7"
                ],
                "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
              },
              "publicEndpoint": {
                "type": "object",
                "properties": {
                  "port": {
                    "type": "number"
                  },
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "http",
                      "tcp",
                      "udp"
                    ]
                  },
                  "subdomain": {
                    "type": "string"
                  },
                  "httpConfig": {
                    "type": "object",
                    "properties": {
                      "ssl": {
                        "type": "boolean"
                      },
                      "forceSsl": {
                        "type": "boolean"
                      },
                      "templates": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "security-headers",
                            "basic-caching"
                          ]
                        }
                      },
                      "extraConfig": {
                        "type": "string"
                      },
                      "proxySetHeader": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "cloudflareEnabled": {
                        "type": "boolean"
                      }
                    },
                    "required": [],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "port"
                ],
                "additionalProperties": false
              },
              "restartPolicy": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "enum": [
                      "always",
                      "no",
                      "unless-stopped",
                      "on-failure"
                    ]
                  },
                  "maximumRetryCount": {
                    "type": "number"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              },
              "security": {
                "type": "object",
                "properties": {
                  "addCapabilities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "dropCapabilities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "networkAliases": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "networkAliasId": {
                "type": "string"
              },
              "env": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    },
                    "secret": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "key",
                    "value"
                  ],
                  "additionalProperties": false
                }
              },
              "ports": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "container": {
                      "type": "number"
                    },
                    "protocol": {
                      "type": "string",
                      "enum": [
                        "TCP",
                        "UDP",
                        "HTTP"
                      ]
                    },
                    "host": {
                      "type": "number"
                    },
                    "hostIp": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "container",
                    "protocol"
                  ],
                  "additionalProperties": false
                }
              },
              "mounts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "volume": {
                      "type": "string"
                    },
                    "mountPath": {
                      "type": "string"
                    },
                    "readOnly": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "volume",
                    "mountPath"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "id",
              "name",
              "source",
              "kind",
              "stage",
              "dependsOn",
              "tier",
              "resources",
              "runtime",
              "process",
              "restartPolicy",
              "security",
              "networkAliases",
              "networkAliasId",
              "env",
              "ports",
              "mounts"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "version",
        "volumes",
        "containers"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "name",
    "spec"
  ],
  "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"
            },
            "savedStackId": {
              "type": "string"
            },
            "updated": {
              "type": "boolean"
            }
          },
          "required": [
            "success",
            "savedStackId",
            "updated"
          ],
          "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,
        "savedStackId": "string",
        "updated": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList a user's saved Compose stacksDetails +/api/v1/projects/:projectId/compose/stacks

Returns all Compose stacks the current user has saved for a project, ordered by most recently updated, with each stack's full parsed spec.

  • Only stacks saved by the requesting user are returned; stacks are scoped per-user, not shared across the project's team.
  • Requires read access to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "spec": {
                "type": "object",
                "properties": {
                  "version": {
                    "const": "1.0",
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "credentials": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "service": {
                          "type": "string"
                        },
                        "username": {
                          "type": "string"
                        },
                        "passwordSecret": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "service",
                        "username",
                        "passwordSecret"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "volumes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "sizeMB": {
                          "type": "number"
                        },
                        "driver": {
                          "type": "string"
                        },
                        "labels": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "name"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "containers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "source": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "const": "docker",
                                  "type": "string"
                                },
                                "image": {
                                  "type": "string"
                                },
                                "registryAuth": {
                                  "type": "object",
                                  "properties": {
                                    "registry": {
                                      "type": "string"
                                    },
                                    "username": {
                                      "type": "string"
                                    },
                                    "password": {
                                      "type": "string"
                                    }
                                  },
                                  "required": [],
                                  "additionalProperties": false
                                }
                              },
                              "required": [
                                "type",
                                "image"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "const": "template",
                                  "type": "string"
                                },
                                "templateId": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "type",
                                "templateId"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "const": "gitBuild",
                                  "type": "string"
                                },
                                "provider": {
                                  "type": "string",
                                  "enum": [
                                    "github",
                                    "self_hosted"
                                  ]
                                },
                                "repository": {
                                  "type": "string"
                                },
                                "ref": {
                                  "type": "string"
                                },
                                "commitSha": {
                                  "type": "string"
                                },
                                "context": {
                                  "type": "string"
                                },
                                "dockerfile": {
                                  "type": "string"
                                },
                                "args": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  }
                                },
                                "target": {
                                  "type": "string"
                                },
                                "imageName": {
                                  "type": "string"
                                },
                                "accessToken": {
                                  "type": "string"
                                },
                                "autoDeploy": {
                                  "type": "boolean"
                                },
                                "branchAutoDeploy": {
                                  "type": "boolean"
                                }
                              },
                              "required": [
                                "type",
                                "repository",
                                "ref",
                                "context",
                                "dockerfile"
                              ],
                              "additionalProperties": false
                            }
                          ]
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "service",
                            "job"
                          ]
                        },
                        "stage": {
                          "type": "number"
                        },
                        "dependsOn": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "service": {
                                    "type": "string"
                                  },
                                  "condition": {
                                    "type": "string",
                                    "enum": [
                                      "service_started",
                                      "service_healthy",
                                      "service_completed_successfully"
                                    ]
                                  }
                                },
                                "required": [
                                  "service"
                                ],
                                "additionalProperties": false
                              }
                            ]
                          }
                        },
                        "tier": {
                          "type": "string",
                          "enum": [
                            "shared",
                            "docker-os",
                            "dedicated",
                            "auto-scale"
                          ]
                        },
                        "resources": {
                          "type": "object",
                          "properties": {
                            "cpu": {
                              "type": "number"
                            },
                            "ram": {
                              "type": "number"
                            },
                            "storage": {
                              "type": "number"
                            },
                            "maxCpu": {
                              "type": "number"
                            },
                            "maxRam": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": false
                        },
                        "runtime": {
                          "type": "object",
                          "properties": {
                            "autoSleep": {
                              "type": "boolean"
                            },
                            "autoScale": {
                              "type": "boolean"
                            },
                            "is24x7": {
                              "type": "boolean"
                            },
                            "autoScaleMode": {
                              "type": "string",
                              "enum": [
                                "vertical",
                                "horizontal"
                              ]
                            }
                          },
                          "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
                        },
                        "publicEndpoint": {
                          "type": "object",
                          "properties": {
                            "port": {
                              "type": "number"
                            },
                            "protocol": {
                              "type": "string",
                              "enum": [
                                "http",
                                "tcp",
                                "udp"
                              ]
                            },
                            "subdomain": {
                              "type": "string"
                            },
                            "httpConfig": {
                              "type": "object",
                              "properties": {
                                "ssl": {
                                  "type": "boolean"
                                },
                                "forceSsl": {
                                  "type": "boolean"
                                },
                                "templates": {
                                  "type": "array",
                                  "items": {
                                    "type": "string",
                                    "enum": [
                                      "security-headers",
                                      "basic-caching"
                                    ]
                                  }
                                },
                                "extraConfig": {
                                  "type": "string"
                                },
                                "proxySetHeader": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  }
                                },
                                "cloudflareEnabled": {
                                  "type": "boolean"
                                }
                              },
                              "required": [],
                              "additionalProperties": false
                            }
                          },
                          "required": [
                            "port"
                          ],
                          "additionalProperties": false
                        },
                        "restartPolicy": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "enum": [
                                "always",
                                "no",
                                "unless-stopped",
                                "on-failure"
                              ]
                            },
                            "maximumRetryCount": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "name"
                          ],
                          "additionalProperties": false
                        },
                        "security": {
                          "type": "object",
                          "properties": {
                            "addCapabilities": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "dropCapabilities": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [],
                          "additionalProperties": false
                        },
                        "networkAliases": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "networkAliasId": {
                          "type": "string"
                        },
                        "env": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "secret": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "key",
                              "value"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "ports": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "container": {
                                "type": "number"
                              },
                              "protocol": {
                                "type": "string",
                                "enum": [
                                  "TCP",
                                  "UDP",
                                  "HTTP"
                                ]
                              },
                              "host": {
                                "type": "number"
                              },
                              "hostIp": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "container",
                              "protocol"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "mounts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "volume": {
                                "type": "string"
                              },
                              "mountPath": {
                                "type": "string"
                              },
                              "readOnly": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "volume",
                              "mountPath"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "name",
                        "source"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "version",
                  "containers"
                ],
                "additionalProperties": false
              },
              "createdAt": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name",
              "spec",
              "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",
          "name": "string",
          "spec": {
            "version": "string",
            "name": "string",
            "description": "string",
            "credentials": [
              {
                "name": "string",
                "service": "string",
                "username": "string",
                "passwordSecret": "string"
              }
            ],
            "volumes": [
              {
                "name": "string",
                "sizeMB": 0,
                "driver": "string",
                "labels": null
              }
            ],
            "containers": [
              {
                "name": "string",
                "source": null,
                "kind": "service",
                "stage": 0,
                "dependsOn": [
                  null
                ],
                "tier": "shared",
                "resources": {
                  "cpu": 0,
                  "ram": 0,
                  "storage": 0,
                  "maxCpu": 0,
                  "maxRam": 0
                },
                "runtime": {
                  "autoSleep": true,
                  "autoScale": true,
                  "is24x7": true,
                  "autoScaleMode": "vertical"
                },
                "process": {
                  "command": [
                    "string"
                  ],
                  "entrypoint": [
                    "string"
                  ],
                  "workingDir": "string"
                },
                "healthcheck": {
                  "test": [
                    "string"
                  ],
                  "interval": "string",
                  "timeout": "string",
                  "startPeriod": "string",
                  "retries": 0
                },
                "publicEndpoint": {
                  "port": 0,
                  "protocol": "http",
                  "subdomain": "string",
                  "httpConfig": {
                    "ssl": true,
                    "forceSsl": true,
                    "templates": [
                      "security-headers"
                    ],
                    "extraConfig": "string",
                    "proxySetHeader": null,
                    "cloudflareEnabled": true
                  }
                },
                "restartPolicy": {
                  "name": "always",
                  "maximumRetryCount": 0
                },
                "security": {
                  "addCapabilities": [
                    "string"
                  ],
                  "dropCapabilities": [
                    "string"
                  ]
                },
                "networkAliases": [
                  "string"
                ],
                "networkAliasId": "string",
                "env": [
                  {
                    "key": "string",
                    "value": "string",
                    "secret": true
                  }
                ],
                "ports": [
                  {
                    "container": 0,
                    "protocol": "TCP",
                    "host": 0,
                    "hostIp": "string"
                  }
                ],
                "mounts": [
                  {
                    "volume": "string",
                    "mountPath": "string",
                    "readOnly": true
                  }
                ]
              }
            ]
          },
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDelete a saved Compose stackDetails +/api/v1/projects/:projectId/compose/stacks/:stackId/delete

Permanently deletes one previously saved Compose stack belonging to the current user and project.

  • Returns a 404 if no matching stack exists for that user/project/stack ID combination.
  • This only removes the saved definition and has no effect on any already-running containers from that stack.
  • Requires read access to the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
stackIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            }
          },
          "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
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETBrowse built-in Compose stack templatesDetails +/api/v1/projects/:projectId/compose/templates

Returns a paginated, searchable, filterable catalog of built-in Compose templates, supporting free-text search across name/description/category/tags and filtering by category.

  • Results are sorted with popular templates first, then by tested status (passed/partial/untested/failed), then alphabetically.
  • Requires authentication only; templates are not project-specific despite the project ID in the path.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
pagequeryNonumber—
pageSizequeryNonumber—
queryqueryNostring—
categoryqueryNostring—
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"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "icon": {
                    "type": "string",
                    "nullable": true
                  },
                  "category": {
                    "type": "string",
                    "nullable": true
                  },
                  "popular": {
                    "type": "boolean"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "spec": {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": "1.0",
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "credentials": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "service": {
                              "type": "string"
                            },
                            "username": {
                              "type": "string"
                            },
                            "passwordSecret": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "service",
                            "username",
                            "passwordSecret"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "volumes": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "sizeMB": {
                              "type": "number"
                            },
                            "driver": {
                              "type": "string"
                            },
                            "labels": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [
                            "name"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "containers": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "source": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "const": "docker",
                                      "type": "string"
                                    },
                                    "image": {
                                      "type": "string"
                                    },
                                    "registryAuth": {
                                      "type": "object",
                                      "properties": {
                                        "registry": {
                                          "type": "string"
                                        },
                                        "username": {
                                          "type": "string"
                                        },
                                        "password": {
                                          "type": "string"
                                        }
                                      },
                                      "required": [],
                                      "additionalProperties": false
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "image"
                                  ],
                                  "additionalProperties": false
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "const": "template",
                                      "type": "string"
                                    },
                                    "templateId": {
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "templateId"
                                  ],
                                  "additionalProperties": false
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "const": "gitBuild",
                                      "type": "string"
                                    },
                                    "provider": {
                                      "type": "string",
                                      "enum": [
                                        "github",
                                        "self_hosted"
                                      ]
                                    },
                                    "repository": {
                                      "type": "string"
                                    },
                                    "ref": {
                                      "type": "string"
                                    },
                                    "commitSha": {
                                      "type": "string"
                                    },
                                    "context": {
                                      "type": "string"
                                    },
                                    "dockerfile": {
                                      "type": "string"
                                    },
                                    "args": {
                                      "type": "object",
                                      "additionalProperties": {
                                        "type": "string"
                                      }
                                    },
                                    "target": {
                                      "type": "string"
                                    },
                                    "imageName": {
                                      "type": "string"
                                    },
                                    "accessToken": {
                                      "type": "string"
                                    },
                                    "autoDeploy": {
                                      "type": "boolean"
                                    },
                                    "branchAutoDeploy": {
                                      "type": "boolean"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "repository",
                                    "ref",
                                    "context",
                                    "dockerfile"
                                  ],
                                  "additionalProperties": false
                                }
                              ]
                            },
                            "kind": {
                              "type": "string",
                              "enum": [
                                "service",
                                "job"
                              ]
                            },
                            "stage": {
                              "type": "number"
                            },
                            "dependsOn": {
                              "type": "array",
                              "items": {
                                "oneOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "service": {
                                        "type": "string"
                                      },
                                      "condition": {
                                        "type": "string",
                                        "enum": [
                                          "service_started",
                                          "service_healthy",
                                          "service_completed_successfully"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "service"
                                    ],
                                    "additionalProperties": false
                                  }
                                ]
                              }
                            },
                            "tier": {
                              "type": "string",
                              "enum": [
                                "shared",
                                "docker-os",
                                "dedicated",
                                "auto-scale"
                              ]
                            },
                            "resources": {
                              "type": "object",
                              "properties": {
                                "cpu": {
                                  "type": "number"
                                },
                                "ram": {
                                  "type": "number"
                                },
                                "storage": {
                                  "type": "number"
                                },
                                "maxCpu": {
                                  "type": "number"
                                },
                                "maxRam": {
                                  "type": "number"
                                }
                              },
                              "required": [],
                              "additionalProperties": false
                            },
                            "runtime": {
                              "type": "object",
                              "properties": {
                                "autoSleep": {
                                  "type": "boolean"
                                },
                                "autoScale": {
                                  "type": "boolean"
                                },
                                "is24x7": {
                                  "type": "boolean"
                                },
                                "autoScaleMode": {
                                  "type": "string",
                                  "enum": [
                                    "vertical",
                                    "horizontal"
                                  ]
                                }
                              },
                              "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
                            },
                            "publicEndpoint": {
                              "type": "object",
                              "properties": {
                                "port": {
                                  "type": "number"
                                },
                                "protocol": {
                                  "type": "string",
                                  "enum": [
                                    "http",
                                    "tcp",
                                    "udp"
                                  ]
                                },
                                "subdomain": {
                                  "type": "string"
                                },
                                "httpConfig": {
                                  "type": "object",
                                  "properties": {
                                    "ssl": {
                                      "type": "boolean"
                                    },
                                    "forceSsl": {
                                      "type": "boolean"
                                    },
                                    "templates": {
                                      "type": "array",
                                      "items": {
                                        "type": "string",
                                        "enum": [
                                          "security-headers",
                                          "basic-caching"
                                        ]
                                      }
                                    },
                                    "extraConfig": {
                                      "type": "string"
                                    },
                                    "proxySetHeader": {
                                      "type": "object",
                                      "additionalProperties": {
                                        "type": "string"
                                      }
                                    },
                                    "cloudflareEnabled": {
                                      "type": "boolean"
                                    }
                                  },
                                  "required": [],
                                  "additionalProperties": false
                                }
                              },
                              "required": [
                                "port"
                              ],
                              "additionalProperties": false
                            },
                            "restartPolicy": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "enum": [
                                    "always",
                                    "no",
                                    "unless-stopped",
                                    "on-failure"
                                  ]
                                },
                                "maximumRetryCount": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "name"
                              ],
                              "additionalProperties": false
                            },
                            "security": {
                              "type": "object",
                              "properties": {
                                "addCapabilities": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "dropCapabilities": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": [],
                              "additionalProperties": false
                            },
                            "networkAliases": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "networkAliasId": {
                              "type": "string"
                            },
                            "env": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "value": {
                                    "type": "string"
                                  },
                                  "secret": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "key",
                                  "value"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "ports": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "container": {
                                    "type": "number"
                                  },
                                  "protocol": {
                                    "type": "string",
                                    "enum": [
                                      "TCP",
                                      "UDP",
                                      "HTTP"
                                    ]
                                  },
                                  "host": {
                                    "type": "number"
                                  },
                                  "hostIp": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "container",
                                  "protocol"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "mounts": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "volume": {
                                    "type": "string"
                                  },
                                  "mountPath": {
                                    "type": "string"
                                  },
                                  "readOnly": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "volume",
                                  "mountPath"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": [
                            "name",
                            "source"
                          ],
                          "additionalProperties": false
                        }
                      }
                    },
                    "required": [
                      "version",
                      "containers"
                    ],
                    "additionalProperties": false
                  },
                  "createdAt": {
                    "type": "string"
                  },
                  "screenshots": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tested": {
                    "type": "boolean"
                  },
                  "testedStatus": {
                    "type": "string",
                    "enum": [
                      "failed",
                      "partial",
                      "passed",
                      "untested"
                    ]
                  },
                  "testedNotes": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "description",
                  "icon",
                  "category",
                  "popular",
                  "enabled",
                  "spec",
                  "createdAt"
                ],
                "additionalProperties": false
              }
            },
            "page": {
              "type": "number"
            },
            "pageSize": {
              "type": "number"
            },
            "total": {
              "type": "number"
            },
            "totalPages": {
              "type": "number"
            },
            "query": {
              "type": "string"
            }
          },
          "required": [
            "items",
            "page",
            "pageSize",
            "total",
            "totalPages",
            "query"
          ],
          "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",
            "description": "string",
            "icon": "string",
            "category": "string",
            "popular": true,
            "enabled": true,
            "spec": {
              "version": "string",
              "name": "string",
              "description": "string",
              "credentials": [
                {
                  "name": "string",
                  "service": "string",
                  "username": "string",
                  "passwordSecret": "string"
                }
              ],
              "volumes": [
                {
                  "name": "string",
                  "sizeMB": 0,
                  "driver": "string",
                  "labels": null
                }
              ],
              "containers": [
                {
                  "name": "string",
                  "source": null,
                  "kind": "service",
                  "stage": 0,
                  "dependsOn": [
                    null
                  ],
                  "tier": "shared",
                  "resources": {
                    "cpu": 0,
                    "ram": 0,
                    "storage": 0,
                    "maxCpu": 0,
                    "maxRam": 0
                  },
                  "runtime": {
                    "autoSleep": true,
                    "autoScale": true,
                    "is24x7": true,
                    "autoScaleMode": "vertical"
                  },
                  "process": {
                    "command": [
                      "string"
                    ],
                    "entrypoint": [
                      "string"
                    ],
                    "workingDir": "string"
                  },
                  "healthcheck": {
                    "test": [
                      "string"
                    ],
                    "interval": "string",
                    "timeout": "string",
                    "startPeriod": "string",
                    "retries": 0
                  },
                  "publicEndpoint": {
                    "port": 0,
                    "protocol": "http",
                    "subdomain": "string",
                    "httpConfig": {
                      "ssl": true,
                      "forceSsl": true,
                      "templates": [
                        "security-headers"
                      ],
                      "extraConfig": "string",
                      "proxySetHeader": null,
                      "cloudflareEnabled": true
                    }
                  },
                  "restartPolicy": {
                    "name": "always",
                    "maximumRetryCount": 0
                  },
                  "security": {
                    "addCapabilities": [
                      "string"
                    ],
                    "dropCapabilities": [
                      "string"
                    ]
                  },
                  "networkAliases": [
                    "string"
                  ],
                  "networkAliasId": "string",
                  "env": [
                    {
                      "key": "string",
                      "value": "string",
                      "secret": true
                    }
                  ],
                  "ports": [
                    {
                      "container": 0,
                      "protocol": "TCP",
                      "host": 0,
                      "hostIp": "string"
                    }
                  ],
                  "mounts": [
                    {
                      "volume": "string",
                      "mountPath": "string",
                      "readOnly": true
                    }
                  ]
                }
              ]
            },
            "createdAt": "string",
            "screenshots": [
              "string"
            ],
            "tags": [
              "string"
            ],
            "tested": true,
            "testedStatus": "failed",
            "testedNotes": "string"
          }
        ],
        "page": 0,
        "pageSize": 0,
        "total": 0,
        "totalPages": 0,
        "query": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

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