Hubfly spaceDocs
Console

Cell API · Dashboard

Endpoints, domains & balancing

Publish container endpoints, attach domains, reserve ports, and distribute traffic across replicas.

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. Start a listening service in the container and note its internal port.
  2. Create an HTTP or TCP endpoint, attach an owned domain if needed, and inspect route or certificate status.
  3. Use load balancers and replicas when one container is not enough.

Inspect container networking

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

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

Open interactive API explorer
MethodPathPurpose
POST/api/v1/projects/:projectId/containers/:containerId/network/domains/attachAttach one of the caller's verified custom domains to a container
POST/api/v1/projects/:projectId/containers/:containerId/network/domains/wildcard-cert/requestRequest a wildcard TLS certificate for a domain
POST/api/v1/projects/:projectId/containers/:containerId/network/domains/wildcard-cert/statusCheck wildcard TLS certificate issuance status
POST/api/v1/projects/:projectId/containers/:containerId/network/domains/wildcard-cert/verifyVerify DNS TXT record and issue wildcard certificate
POST/api/v1/projects/:projectId/containers/:containerId/network/domains/:domainId/removeDetach a custom domain from a container
POST/api/v1/projects/:projectId/containers/:containerId/network/domains/:domainId/updateUpdate port, TLS, or cache settings for an attached domain
POST/api/v1/projects/:projectId/containers/:containerId/network/endpoints/createCreate a platform-provided public endpoint (HTTP or TCP)
POST/api/v1/projects/:projectId/containers/:containerId/network/endpoints/:endpointId/removeRemove a platform-provided public endpoint
POST/api/v1/projects/:projectId/containers/:containerId/network/endpoints/:endpointId/updateUpdate the target port or HTTP settings of an endpoint
PUT/api/v1/projects/:projectId/containers/:containerId/network/image-optimization/updateConfigure image optimization
GET/api/v1/projects/:projectId/containers/:containerId/networkGet a container's networking overview: endpoints and domains
POST/api/v1/projects/:projectId/containers/:containerId/network/purge-cachePurge the edge cache for a container's domain/route
POST/api/v1/projects/:projectId/containers/:containerId/network/redirectConfigure an HTTP redirect from one hostname to another
POST/api/v1/projects/:projectId/containers/:containerId/network/syncRe-sync and refresh a container's domain/SSL status from the proxy
POST/api/v1/projects/:projectId/load-balancers/createCreate a new load balancer group
POST/api/v1/projects/:projectId/load-balancers/generate-domainGenerate an available hubfly.app domain name
GET/api/v1/projects/:projectId/load-balancersList all load balancer groups for a project
POST/api/v1/projects/:projectId/load-balancers/:lbId/custom-domains/attachAttach a verified custom domain to a load balancer
DELETE/api/v1/projects/:projectId/load-balancers/:lbId/deleteDelete a load balancer group
POST/api/v1/projects/:projectId/load-balancers/:lbId/domains/createAdd a hubfly-managed domain to a load balancer
DELETE/api/v1/projects/:projectId/load-balancers/:lbId/domains/:domainId/deleteRemove a domain from a load balancer
POST/api/v1/projects/:projectId/load-balancers/:lbId/domains/:domainId/redirectConfigure a redirect for a load balancer domain
PUT/api/v1/projects/:projectId/load-balancers/:lbId/domains/:domainId/updateUpdate a load balancer domain's SSL/template settings
GET/api/v1/projects/:projectId/load-balancers/:lbIdGet a single load balancer group's details
POST/api/v1/projects/:projectId/load-balancers/:lbId/syncRe-sync a load balancer's domains to the proxy
POST/api/v1/projects/:projectId/load-balancers/:lbId/targets/createAdd a container as a load balancer target
DELETE/api/v1/projects/:projectId/load-balancers/:lbId/targets/:targetId/deleteRemove a target from a load balancer
PUT/api/v1/projects/:projectId/load-balancers/:lbId/targets/:targetId/updateUpdate a load balancer target's port or weight
PUT/api/v1/projects/:projectId/load-balancers/:lbId/updateUpdate a load balancer group's settings
GET/api/v1/projects/:projectId/portsList the caller's reserved TCP/UDP ports
POST/api/v1/projects/:projectId/ports/reserveReserve a block of host ports in a region
DELETE/api/v1/projects/:projectId/ports/:reservationIdRelease a port reservation
POST/api/v1/projects/:projectId/ports/:reservationId/mapMap a reserved host port to a container port
POST/api/v1/projects/:projectId/ports/:reservationId/unmapUnmap a host port from its container
GET/api/v1/projects/:projectId/subdomainsList the caller's reserved subdomains
POST/api/v1/projects/:projectId/subdomains/reserveReserve a hubfly.app subdomain for a container
DELETE/api/v1/projects/:projectId/subdomains/:subdomainIdRelease a reserved subdomain
POSTAttach one of the caller's verified custom domains to a containerDetails +/api/v1/projects/:projectId/containers/:containerId/network/domains/attach

Points an already-verified custom domain owned by the calling user at a container's port, preserving any existing firewall rules and applying the requested TLS/cache/security-template settings.

  • If the domain is currently attached to a different container or a load-balancer group, the call fails with a transfer-required conflict unless approveTransfer is set.
  • When approveTransfer is set, the domain is moved from its old attachment automatically.
  • Requires container:update permission.
  • SSL-enabled domains trigger a best-effort request to kick off certificate provisioning.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
domainIdstringYes
portstringYes
sslbooleanYes
forceSslbooleanYes
wildcardPrefixstringNo
templatesstring[]No
cacheobjectNo
approveTransferbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "domainId": {
      "type": "string"
    },
    "port": {
      "type": "string"
    },
    "ssl": {
      "type": "boolean"
    },
    "forceSsl": {
      "type": "boolean"
    },
    "wildcardPrefix": {
      "type": "string"
    },
    "templates": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cache": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "defaultTtl": {
          "type": "number"
        },
        "serveStale": {
          "type": "number"
        },
        "bypassCookies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "bypassHeaders": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "enabled",
        "defaultTtl",
        "serveStale"
      ],
      "additionalProperties": false
    },
    "approveTransfer": {
      "type": "boolean"
    }
  },
  "required": [
    "domainId",
    "port",
    "ssl",
    "forceSsl"
  ],
  "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"
            },
            "transferred": {
              "type": "boolean"
            }
          },
          "required": [
            "success",
            "transferred"
          ],
          "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,
        "transferred": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRequest a wildcard TLS certificate for a domainDetails +/api/v1/projects/:projectId/containers/:containerId/network/domains/wildcard-cert/request

Initiates an automated wildcard Let's Encrypt TLS certificate request (e.g. *.example.com) for a container custom domain.

  • Generates required DNS-01 ACME challenge TXT records.
  • Requires network:manage permission on the project.
  • The base domain must be verified prior to requesting a wildcard certificate.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
customDomainIdstringYes
domainNamestringYes
wildcardPrefixstringYes
emailstringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "customDomainId": {
      "type": "string"
    },
    "domainName": {
      "type": "string"
    },
    "wildcardPrefix": {
      "type": "string"
    },
    "email": {
      "type": "string"
    }
  },
  "required": [
    "customDomainId",
    "domainName",
    "wildcardPrefix",
    "email"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "sessionId": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "failed",
                "issued",
                "pending_dns",
                "provisioning_dns"
              ]
            },
            "dnsRecords": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "domain",
                  "name",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "lastError": {
              "type": "string"
            }
          },
          "required": [
            "sessionId",
            "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": {
        "sessionId": "string",
        "status": "failed",
        "dnsRecords": [
          {
            "domain": "string",
            "name": "string",
            "value": "string"
          }
        ],
        "lastError": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCheck wildcard TLS certificate issuance statusDetails +/api/v1/projects/:projectId/containers/:containerId/network/domains/wildcard-cert/status

Returns the current state, expiration, ACME challenge records, and verification status of a requested wildcard TLS certificate.

  • Requires network:manage permission on the project.
  • Returns active status once ACME validation completes.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
sessionIdstringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string"
    }
  },
  "required": [
    "sessionId"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "sessionId": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "domainName": {
              "type": "string"
            },
            "wildcardPrefix": {
              "type": "string"
            },
            "dnsRecords": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "domain",
                  "name",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "issuedAt": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            },
            "lastError": {
              "type": "string"
            }
          },
          "required": [
            "sessionId",
            "status",
            "domainName"
          ],
          "additionalProperties": false,
          "nullable": true
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "sessionId": "string",
        "status": "string",
        "domainName": "string",
        "wildcardPrefix": "string",
        "dnsRecords": [
          {
            "domain": "string",
            "name": "string",
            "value": "string"
          }
        ],
        "issuedAt": "string",
        "expiresAt": "string",
        "lastError": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTVerify DNS TXT record and issue wildcard certificateDetails +/api/v1/projects/:projectId/containers/:containerId/network/domains/wildcard-cert/verify

Triggers DNS-01 TXT record verification against public nameservers to complete wildcard TLS certificate issuance.

  • Requires network:manage permission on the project.
  • If TXT record propagation is incomplete, retry after DNS TTL expires.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
sessionIdstringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string"
    }
  },
  "required": [
    "sessionId"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "failed",
                "issued",
                "provisioning_dns"
              ]
            },
            "expiresAt": {
              "type": "string"
            },
            "lastError": {
              "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": "failed",
        "expiresAt": "string",
        "lastError": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTDetach a custom domain from a containerDetails +/api/v1/projects/:projectId/containers/:containerId/network/domains/:domainId/remove

Removes a previously attached custom domain (and any redirect rule for it) from a container, making the domain available to attach elsewhere.

  • The domain must currently belong to the caller and be attached to this specific container, otherwise returns a not-found error.
  • Requires container:update permission.
  • Cleanup of the underlying route is best-effort and won't block detachment if it fails.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
domainIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            }
          },
          "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"
      }
    }
POSTUpdate port, TLS, or cache settings for an attached domainDetails +/api/v1/projects/:projectId/containers/:containerId/network/domains/:domainId/update

Reconfigures an already-attached custom domain's target port, SSL/force-HTTPS settings, security templates, and cache behavior, while preserving existing firewall rules.

  • Any existing redirect rule for that hostname is cleared first.
  • The domain must be owned by the caller and already attached to this container.
  • Requires container:update permission.
  • Returns a 409 if the container's runtime address isn't available yet.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
domainIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
portstringYes
sslbooleanYes
forceSslbooleanYes
templatesstring[]No
cacheobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "port": {
      "type": "string"
    },
    "ssl": {
      "type": "boolean"
    },
    "forceSsl": {
      "type": "boolean"
    },
    "templates": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cache": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "defaultTtl": {
          "type": "number"
        },
        "serveStale": {
          "type": "number"
        },
        "bypassCookies": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "bypassHeaders": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "enabled",
        "defaultTtl",
        "serveStale"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "port",
    "ssl",
    "forceSsl"
  ],
  "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"
            }
          },
          "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"
      }
    }
POSTCreate a platform-provided public endpoint (HTTP or TCP)Details +/api/v1/projects/:projectId/containers/:containerId/network/endpoints/create

Provisions a new publicly reachable endpoint for a container port: either an HTTP route on a hubfly-managed subdomain (auto-generated or caller-supplied) or a TCP stream on an assigned public port.

  • If a caller-supplied subdomain collides with an existing one, a different one is generated automatically.
  • Free-tier ("shared" tier) containers are capped at 2 platform-provided HTTP endpoints.
  • Requires container:update permission.
  • The container must have a resolvable runtime address.
  • SSL-enabled HTTP endpoints trigger a best-effort request to kick off certificate provisioning.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
portnumberYes
protocolhttp | tcp | udpNo
subdomainstringNo
isWildcardbooleanNo
httpConfigobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "port": {
      "type": "number"
    },
    "protocol": {
      "type": "string",
      "enum": [
        "http",
        "tcp",
        "udp"
      ]
    },
    "subdomain": {
      "type": "string"
    },
    "isWildcard": {
      "type": "boolean"
    },
    "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
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "endpointId": {
              "type": "string"
            },
            "hostname": {
              "type": "string"
            },
            "tunnelUrl": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "endpointId",
            "hostname",
            "tunnelUrl"
          ],
          "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": {
        "endpointId": "string",
        "hostname": "string",
        "tunnelUrl": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRemove a platform-provided public endpointDetails +/api/v1/projects/:projectId/containers/:containerId/network/endpoints/:endpointId/remove

Deletes a previously created public endpoint (HTTP or TCP), including its route and any associated redirect, and removes it from the container's port list.

  • The endpoint is removed even if the underlying cleanup with the network layer fails.
  • Requires container:update permission.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
endpointIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            }
          },
          "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"
      }
    }
POSTUpdate the target port or HTTP settings of an endpointDetails +/api/v1/projects/:projectId/containers/:containerId/network/endpoints/:endpointId/update

Changes an existing public endpoint's backend port and, for HTTP endpoints, its TLS/cache/security-template configuration, while preserving existing firewall rules where possible.

  • For HTTP endpoints, any existing redirect rule on that hostname is removed first.
  • Requires container:update permission.
  • Returns a 409 if the container's runtime address is not yet available.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
endpointIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
portnumberYes
httpConfigobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "port": {
      "type": "number"
    },
    "httpConfig": {
      "type": "object",
      "properties": {
        "ssl": {
          "type": "boolean"
        },
        "forceSsl": {
          "type": "boolean"
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "basic-security",
              "block-bots",
              "security-headers",
              "basic-caching"
            ]
          }
        },
        "extraConfig": {
          "type": "string"
        },
        "proxySetHeader": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "cloudflareEnabled": {
          "type": "boolean"
        },
        "cache": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "defaultTtl": {
              "type": "number"
            },
            "serveStale": {
              "type": "number"
            },
            "bypassCookies": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "bypassHeaders": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "enabled",
            "defaultTtl",
            "serveStale"
          ],
          "additionalProperties": false
        }
      },
      "required": [],
      "additionalProperties": false
    }
  },
  "required": [
    "port"
  ],
  "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"
            }
          },
          "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"
      }
    }
PUTConfigure image optimizationDetails +/api/v1/projects/:projectId/containers/:containerId/network/image-optimization/update

Turn on and configure image optimization for one container domain (routeType container_endpoint or custom_domain), or turn it off with settings: null or enabled: false. Returns the effective settings and a syncStatus of pending, active or error.

  • Requires the container:update project permission.
  • The settings object replaces the stored one: omitted fields take their defaults (mode both, formats avif/webp, quality 85, maxWidth/maxHeight 4096, urlPrefix /cdn-cgi/image/, minSavings 5).
  • Limits: quality and saveDataQuality 1–100, avifSpeed 0–10, maxWidth/maxHeight up to 16384, up to 64 allowedWidths, minSavings 0–90; violations return 400 INVALID_IMAGE_OPTIMIZATION.
  • Free containers that are read-only for a zero balance return 423 FREE_CONTAINER_READ_ONLY.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
routeTypecustom_domain | container_endpointYes
routeIdstringYes
settingsobjectYes
Complete request schema
{
  "type": "object",
  "properties": {
    "routeType": {
      "type": "string",
      "enum": [
        "custom_domain",
        "container_endpoint"
      ]
    },
    "routeId": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "auto",
            "params",
            "both"
          ]
        },
        "formats": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "avif",
              "webp"
            ]
          }
        },
        "quality": {
          "type": "number"
        },
        "saveDataQuality": {
          "type": "number"
        },
        "avifSpeed": {
          "type": "number"
        },
        "clientHints": {
          "type": "boolean"
        },
        "maxWidth": {
          "type": "number"
        },
        "maxHeight": {
          "type": "number"
        },
        "allowedWidths": {
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "maxSourceBytes": {
          "type": "number"
        },
        "maxPixels": {
          "type": "number"
        },
        "urlPrefix": {
          "type": "string"
        },
        "avifMaxPixels": {
          "type": "number"
        },
        "minSavings": {
          "type": "number"
        },
        "allowUpscale": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false,
      "nullable": true
    }
  },
  "required": [
    "routeType",
    "routeId",
    "settings"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "settings": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "mode": {
                  "type": "string",
                  "enum": [
                    "auto",
                    "params",
                    "both"
                  ]
                },
                "formats": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "avif",
                      "webp"
                    ]
                  }
                },
                "quality": {
                  "type": "number"
                },
                "saveDataQuality": {
                  "type": "number"
                },
                "avifSpeed": {
                  "type": "number"
                },
                "clientHints": {
                  "type": "boolean"
                },
                "maxWidth": {
                  "type": "number"
                },
                "maxHeight": {
                  "type": "number"
                },
                "allowedWidths": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "maxSourceBytes": {
                  "type": "number"
                },
                "maxPixels": {
                  "type": "number"
                },
                "urlPrefix": {
                  "type": "string"
                },
                "avifMaxPixels": {
                  "type": "number"
                },
                "minSavings": {
                  "type": "number"
                },
                "allowUpscale": {
                  "type": "boolean"
                }
              },
              "required": [
                "enabled",
                "mode",
                "formats",
                "quality",
                "saveDataQuality",
                "avifSpeed",
                "clientHints",
                "maxWidth",
                "maxHeight",
                "allowedWidths",
                "maxSourceBytes",
                "maxPixels",
                "urlPrefix",
                "avifMaxPixels",
                "minSavings",
                "allowUpscale"
              ],
              "additionalProperties": false,
              "nullable": true
            },
            "syncStatus": {
              "type": "string",
              "enum": [
                "pending",
                "active",
                "error"
              ],
              "nullable": true
            },
            "syncError": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "settings",
            "syncStatus",
            "syncError"
          ],
          "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": {
        "settings": {
          "enabled": true,
          "mode": "auto",
          "formats": [
            "avif"
          ],
          "quality": 0,
          "saveDataQuality": 0,
          "avifSpeed": 0,
          "clientHints": true,
          "maxWidth": 0,
          "maxHeight": 0,
          "allowedWidths": [
            0
          ],
          "maxSourceBytes": 0,
          "maxPixels": 0,
          "urlPrefix": "string",
          "avifMaxPixels": 0,
          "minSavings": 0,
          "allowUpscale": true
        },
        "syncStatus": "pending",
        "syncError": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETGet a container's networking overview: endpoints and domainsDetails +/api/v1/projects/:projectId/containers/:containerId/network

Returns the container's public-facing networking state: its platform-provided endpoints with live route and SSL status, the custom domains attached to it, and the caller's other verified domains available to attach.

  • Also returns the expected CNAME target and suggested ports for the container's region.
  • Available to any user with project access.
  • Route and SSL status are checked live rather than read purely from stored state.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "projectId": {
              "type": "string"
            },
            "containerId": {
              "type": "string"
            },
            "containerName": {
              "type": "string"
            },
            "regionId": {
              "type": "string"
            },
            "expectedCnameTarget": {
              "type": "string"
            },
            "suggestedPorts": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "portSuggestions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "port": {
                    "type": "number"
                  },
                  "protocol": {
                    "const": "tcp",
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "domain",
                      "runtime",
                      "configured"
                    ]
                  },
                  "confidence": {
                    "type": "string",
                    "enum": [
                      "open",
                      "configured"
                    ]
                  }
                },
                "required": [
                  "port",
                  "protocol",
                  "source",
                  "confidence"
                ],
                "additionalProperties": false
              }
            },
            "domainAccess": {
              "type": "object",
              "properties": {
                "isProjectOwner": {
                  "type": "boolean"
                },
                "canAttachOwnerDomains": {
                  "type": "boolean"
                }
              },
              "required": [
                "isProjectOwner",
                "canAttachOwnerDomains"
              ],
              "additionalProperties": false
            },
            "availableOwnedDomains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "error",
                      "verified"
                    ]
                  },
                  "verificationFqdn": {
                    "type": "string",
                    "nullable": true
                  },
                  "verificationToken": {
                    "type": "string",
                    "nullable": true
                  },
                  "lastError": {
                    "type": "string",
                    "nullable": true
                  },
                  "containerId": {
                    "type": "string",
                    "nullable": true
                  },
                  "port": {
                    "type": "string",
                    "nullable": true
                  },
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "defaultTtl": {
                        "type": "number"
                      },
                      "serveStale": {
                        "type": "number"
                      },
                      "bypassCookies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "bypassHeaders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "enabled",
                      "defaultTtl",
                      "serveStale"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "domainName",
                  "status",
                  "verificationFqdn",
                  "verificationToken",
                  "lastError",
                  "containerId",
                  "port",
                  "ssl",
                  "forceSsl",
                  "templates"
                ],
                "additionalProperties": false
              }
            },
            "publicEndpoints": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "hostname": {
                    "type": "string"
                  },
                  "port": {
                    "type": "number"
                  },
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "http",
                      "tcp",
                      "udp"
                    ]
                  },
                  "publicPort": {
                    "type": "number",
                    "nullable": true
                  },
                  "tunnelUrl": {
                    "type": "string",
                    "nullable": true
                  },
                  "proxySiteId": {
                    "type": "string",
                    "nullable": true
                  },
                  "httpConfig": {
                    "type": "object",
                    "properties": {
                      "ssl": {
                        "type": "boolean"
                      },
                      "forceSsl": {
                        "type": "boolean"
                      },
                      "templates": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "basic-security",
                            "block-bots",
                            "security-headers",
                            "basic-caching"
                          ]
                        }
                      },
                      "extraConfig": {
                        "type": "string"
                      },
                      "proxySetHeader": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "cloudflareEnabled": {
                        "type": "boolean"
                      },
                      "cache": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "defaultTtl": {
                            "type": "number"
                          },
                          "serveStale": {
                            "type": "number"
                          },
                          "bypassCookies": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "bypassHeaders": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "enabled",
                          "defaultTtl",
                          "serveStale"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "ssl",
                      "forceSsl",
                      "templates"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "live",
                      "redirect",
                      "missing"
                    ]
                  },
                  "redirectTarget": {
                    "type": "string",
                    "nullable": true
                  },
                  "redirectStatusCode": {
                    "type": "number",
                    "nullable": true
                  },
                  "sslStatus": {
                    "type": "object",
                    "properties": {
                      "state": {
                        "type": "string",
                        "enum": [
                          "error",
                          "secure",
                          "issuing",
                          "no_ssl",
                          "not_found",
                          "unavailable"
                        ]
                      },
                      "message": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "state",
                      "message"
                    ],
                    "additionalProperties": false
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "defaultTtl": {
                        "type": "number"
                      },
                      "serveStale": {
                        "type": "number"
                      },
                      "bypassCookies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "bypassHeaders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "enabled",
                      "defaultTtl",
                      "serveStale"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "routeId": {
                    "type": "string"
                  },
                  "imageOptimization": {
                    "type": "object",
                    "properties": {
                      "settings": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "mode": {
                            "type": "string",
                            "enum": [
                              "auto",
                              "params",
                              "both"
                            ]
                          },
                          "formats": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "avif",
                                "webp"
                              ]
                            }
                          },
                          "quality": {
                            "type": "number"
                          },
                          "saveDataQuality": {
                            "type": "number"
                          },
                          "avifSpeed": {
                            "type": "number"
                          },
                          "clientHints": {
                            "type": "boolean"
                          },
                          "maxWidth": {
                            "type": "number"
                          },
                          "maxHeight": {
                            "type": "number"
                          },
                          "allowedWidths": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          },
                          "maxSourceBytes": {
                            "type": "number"
                          },
                          "maxPixels": {
                            "type": "number"
                          },
                          "urlPrefix": {
                            "type": "string"
                          },
                          "avifMaxPixels": {
                            "type": "number"
                          },
                          "minSavings": {
                            "type": "number"
                          },
                          "allowUpscale": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "enabled",
                          "mode",
                          "formats",
                          "quality",
                          "saveDataQuality",
                          "avifSpeed",
                          "clientHints",
                          "maxWidth",
                          "maxHeight",
                          "allowedWidths",
                          "maxSourceBytes",
                          "maxPixels",
                          "urlPrefix",
                          "avifMaxPixels",
                          "minSavings",
                          "allowUpscale"
                        ],
                        "additionalProperties": false,
                        "nullable": true
                      },
                      "syncStatus": {
                        "type": "string",
                        "enum": [
                          "pending",
                          "active",
                          "error"
                        ],
                        "nullable": true
                      },
                      "syncError": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "settings",
                      "syncStatus",
                      "syncError"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "globalHostname": {
                    "type": "string",
                    "nullable": true
                  },
                  "globalHostnameKind": {
                    "type": "string",
                    "enum": [
                      "primary",
                      "alias"
                    ],
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "hostname",
                  "port",
                  "protocol",
                  "publicPort",
                  "tunnelUrl",
                  "proxySiteId",
                  "httpConfig",
                  "kind",
                  "redirectTarget",
                  "redirectStatusCode",
                  "sslStatus",
                  "cache",
                  "routeId",
                  "imageOptimization",
                  "globalHostname",
                  "globalHostnameKind"
                ],
                "additionalProperties": false
              }
            },
            "globalNamesAvailable": {
              "type": "boolean"
            },
            "customDomains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "wildcardPrefix": {
                    "type": "string",
                    "nullable": true
                  },
                  "port": {
                    "type": "string",
                    "nullable": true
                  },
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "error",
                      "verified"
                    ]
                  },
                  "verificationFqdn": {
                    "type": "string",
                    "nullable": true
                  },
                  "verificationToken": {
                    "type": "string",
                    "nullable": true
                  },
                  "lastError": {
                    "type": "string",
                    "nullable": true
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "live",
                      "redirect",
                      "missing"
                    ]
                  },
                  "redirectTarget": {
                    "type": "string",
                    "nullable": true
                  },
                  "redirectStatusCode": {
                    "type": "number",
                    "nullable": true
                  },
                  "sslStatus": {
                    "type": "object",
                    "properties": {
                      "state": {
                        "type": "string",
                        "enum": [
                          "error",
                          "secure",
                          "issuing",
                          "no_ssl",
                          "not_found",
                          "unavailable"
                        ]
                      },
                      "message": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "state",
                      "message"
                    ],
                    "additionalProperties": false
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "defaultTtl": {
                        "type": "number"
                      },
                      "serveStale": {
                        "type": "number"
                      },
                      "bypassCookies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "bypassHeaders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "enabled",
                      "defaultTtl",
                      "serveStale"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "imageOptimization": {
                    "type": "object",
                    "properties": {
                      "settings": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "mode": {
                            "type": "string",
                            "enum": [
                              "auto",
                              "params",
                              "both"
                            ]
                          },
                          "formats": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "avif",
                                "webp"
                              ]
                            }
                          },
                          "quality": {
                            "type": "number"
                          },
                          "saveDataQuality": {
                            "type": "number"
                          },
                          "avifSpeed": {
                            "type": "number"
                          },
                          "clientHints": {
                            "type": "boolean"
                          },
                          "maxWidth": {
                            "type": "number"
                          },
                          "maxHeight": {
                            "type": "number"
                          },
                          "allowedWidths": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          },
                          "maxSourceBytes": {
                            "type": "number"
                          },
                          "maxPixels": {
                            "type": "number"
                          },
                          "urlPrefix": {
                            "type": "string"
                          },
                          "avifMaxPixels": {
                            "type": "number"
                          },
                          "minSavings": {
                            "type": "number"
                          },
                          "allowUpscale": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "enabled",
                          "mode",
                          "formats",
                          "quality",
                          "saveDataQuality",
                          "avifSpeed",
                          "clientHints",
                          "maxWidth",
                          "maxHeight",
                          "allowedWidths",
                          "maxSourceBytes",
                          "maxPixels",
                          "urlPrefix",
                          "avifMaxPixels",
                          "minSavings",
                          "allowUpscale"
                        ],
                        "additionalProperties": false,
                        "nullable": true
                      },
                      "syncStatus": {
                        "type": "string",
                        "enum": [
                          "pending",
                          "active",
                          "error"
                        ],
                        "nullable": true
                      },
                      "syncError": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "settings",
                      "syncStatus",
                      "syncError"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "id",
                  "domainName",
                  "wildcardPrefix",
                  "port",
                  "ssl",
                  "forceSsl",
                  "templates",
                  "status",
                  "verificationFqdn",
                  "verificationToken",
                  "lastError",
                  "kind",
                  "redirectTarget",
                  "redirectStatusCode",
                  "sslStatus",
                  "cache",
                  "imageOptimization"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "projectId",
            "containerId",
            "containerName",
            "regionId",
            "expectedCnameTarget",
            "suggestedPorts",
            "portSuggestions",
            "domainAccess",
            "availableOwnedDomains",
            "publicEndpoints",
            "globalNamesAvailable",
            "customDomains"
          ],
          "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": {
        "projectId": "string",
        "containerId": "string",
        "containerName": "string",
        "regionId": "string",
        "expectedCnameTarget": "string",
        "suggestedPorts": [
          0
        ],
        "portSuggestions": [
          {
            "port": 0,
            "protocol": "string",
            "source": "domain",
            "confidence": "open"
          }
        ],
        "domainAccess": {
          "isProjectOwner": true,
          "canAttachOwnerDomains": true
        },
        "availableOwnedDomains": [
          {
            "id": "string",
            "domainName": "string",
            "status": "pending",
            "verificationFqdn": "string",
            "verificationToken": "string",
            "lastError": "string",
            "containerId": "string",
            "port": "string",
            "ssl": true,
            "forceSsl": true,
            "templates": [
              "string"
            ],
            "cache": {
              "enabled": true,
              "defaultTtl": 0,
              "serveStale": 0,
              "bypassCookies": [
                "string"
              ],
              "bypassHeaders": [
                "string"
              ]
            }
          }
        ],
        "publicEndpoints": [
          {
            "id": "string",
            "hostname": "string",
            "port": 0,
            "protocol": "http",
            "publicPort": 0,
            "tunnelUrl": "string",
            "proxySiteId": "string",
            "httpConfig": {
              "ssl": true,
              "forceSsl": true,
              "templates": [
                "basic-security"
              ],
              "extraConfig": "string",
              "proxySetHeader": null,
              "cloudflareEnabled": true,
              "cache": {
                "enabled": true,
                "defaultTtl": 0,
                "serveStale": 0,
                "bypassCookies": [
                  "string"
                ],
                "bypassHeaders": [
                  "string"
                ]
              }
            },
            "kind": "live",
            "redirectTarget": "string",
            "redirectStatusCode": 0,
            "sslStatus": {
              "state": "error",
              "message": "string"
            },
            "cache": {
              "enabled": true,
              "defaultTtl": 0,
              "serveStale": 0,
              "bypassCookies": [
                "string"
              ],
              "bypassHeaders": [
                "string"
              ]
            },
            "routeId": "string",
            "imageOptimization": {
              "settings": {
                "enabled": true,
                "mode": "auto",
                "formats": [
                  "avif"
                ],
                "quality": 0,
                "saveDataQuality": 0,
                "avifSpeed": 0,
                "clientHints": true,
                "maxWidth": 0,
                "maxHeight": 0,
                "allowedWidths": [
                  0
                ],
                "maxSourceBytes": 0,
                "maxPixels": 0,
                "urlPrefix": "string",
                "avifMaxPixels": 0,
                "minSavings": 0,
                "allowUpscale": true
              },
              "syncStatus": "pending",
              "syncError": "string"
            },
            "globalHostname": "string",
            "globalHostnameKind": "primary"
          }
        ],
        "globalNamesAvailable": true,
        "customDomains": [
          {
            "id": "string",
            "domainName": "string",
            "wildcardPrefix": "string",
            "port": "string",
            "ssl": true,
            "forceSsl": true,
            "templates": [
              "string"
            ],
            "status": "pending",
            "verificationFqdn": "string",
            "verificationToken": "string",
            "lastError": "string",
            "kind": "live",
            "redirectTarget": "string",
            "redirectStatusCode": 0,
            "sslStatus": {
              "state": "error",
              "message": "string"
            },
            "cache": {
              "enabled": true,
              "defaultTtl": 0,
              "serveStale": 0,
              "bypassCookies": [
                "string"
              ],
              "bypassHeaders": [
                "string"
              ]
            },
            "imageOptimization": {
              "settings": {
                "enabled": true,
                "mode": "auto",
                "formats": [
                  "avif"
                ],
                "quality": 0,
                "saveDataQuality": 0,
                "avifSpeed": 0,
                "clientHints": true,
                "maxWidth": 0,
                "maxHeight": 0,
                "allowedWidths": [
                  0
                ],
                "maxSourceBytes": 0,
                "maxPixels": 0,
                "urlPrefix": "string",
                "avifMaxPixels": 0,
                "minSavings": 0,
                "allowUpscale": true
              },
              "syncStatus": "pending",
              "syncError": "string"
            }
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTPurge the edge cache for a container's domain/routeDetails +/api/v1/projects/:projectId/containers/:containerId/network/purge-cache

Clears cached responses for the given hostname's route so subsequent requests are served fresh from the container.

  • Requires container:update permission.
  • The container and route must already exist.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
domainstringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "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"
      }
    }
POSTConfigure an HTTP redirect from one hostname to anotherDetails +/api/v1/projects/:projectId/containers/:containerId/network/redirect

Creates a 302 redirect that sends traffic from a source hostname to a target domain, optionally over HTTPS.

  • Any existing non-redirect route on the source hostname is removed first.
  • Both hostnames are normalized and must differ, or the request is rejected as a bad request.
  • Requires container:update permission.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
hostnamestringYes
targetDomainstringYes
sslbooleanYes
permanentbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    },
    "targetDomain": {
      "type": "string"
    },
    "ssl": {
      "type": "boolean"
    },
    "permanent": {
      "type": "boolean"
    }
  },
  "required": [
    "hostname",
    "targetDomain",
    "ssl"
  ],
  "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"
            }
          },
          "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"
      }
    }
POSTRe-sync and refresh a container's domain/SSL status from the proxyDetails +/api/v1/projects/:projectId/containers/:containerId/network/sync

Re-checks the live TLS/certificate and route status of the container's attached domains and endpoints and refreshes the stored SSL state, returning the same shape as the network details endpoint.

  • Useful for polling after attaching a domain to see when certificate provisioning has completed.
  • Available to any user with project access to the container.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
containerIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "projectId": {
              "type": "string"
            },
            "containerId": {
              "type": "string"
            },
            "containerName": {
              "type": "string"
            },
            "regionId": {
              "type": "string"
            },
            "expectedCnameTarget": {
              "type": "string"
            },
            "suggestedPorts": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "portSuggestions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "port": {
                    "type": "number"
                  },
                  "protocol": {
                    "const": "tcp",
                    "type": "string"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "domain",
                      "runtime",
                      "configured"
                    ]
                  },
                  "confidence": {
                    "type": "string",
                    "enum": [
                      "open",
                      "configured"
                    ]
                  }
                },
                "required": [
                  "port",
                  "protocol",
                  "source",
                  "confidence"
                ],
                "additionalProperties": false
              }
            },
            "domainAccess": {
              "type": "object",
              "properties": {
                "isProjectOwner": {
                  "type": "boolean"
                },
                "canAttachOwnerDomains": {
                  "type": "boolean"
                }
              },
              "required": [
                "isProjectOwner",
                "canAttachOwnerDomains"
              ],
              "additionalProperties": false
            },
            "availableOwnedDomains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "error",
                      "verified"
                    ]
                  },
                  "verificationFqdn": {
                    "type": "string",
                    "nullable": true
                  },
                  "verificationToken": {
                    "type": "string",
                    "nullable": true
                  },
                  "lastError": {
                    "type": "string",
                    "nullable": true
                  },
                  "containerId": {
                    "type": "string",
                    "nullable": true
                  },
                  "port": {
                    "type": "string",
                    "nullable": true
                  },
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "defaultTtl": {
                        "type": "number"
                      },
                      "serveStale": {
                        "type": "number"
                      },
                      "bypassCookies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "bypassHeaders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "enabled",
                      "defaultTtl",
                      "serveStale"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "domainName",
                  "status",
                  "verificationFqdn",
                  "verificationToken",
                  "lastError",
                  "containerId",
                  "port",
                  "ssl",
                  "forceSsl",
                  "templates"
                ],
                "additionalProperties": false
              }
            },
            "publicEndpoints": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "hostname": {
                    "type": "string"
                  },
                  "port": {
                    "type": "number"
                  },
                  "protocol": {
                    "type": "string",
                    "enum": [
                      "http",
                      "tcp",
                      "udp"
                    ]
                  },
                  "publicPort": {
                    "type": "number",
                    "nullable": true
                  },
                  "tunnelUrl": {
                    "type": "string",
                    "nullable": true
                  },
                  "proxySiteId": {
                    "type": "string",
                    "nullable": true
                  },
                  "httpConfig": {
                    "type": "object",
                    "properties": {
                      "ssl": {
                        "type": "boolean"
                      },
                      "forceSsl": {
                        "type": "boolean"
                      },
                      "templates": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "basic-security",
                            "block-bots",
                            "security-headers",
                            "basic-caching"
                          ]
                        }
                      },
                      "extraConfig": {
                        "type": "string"
                      },
                      "proxySetHeader": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "cloudflareEnabled": {
                        "type": "boolean"
                      },
                      "cache": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "defaultTtl": {
                            "type": "number"
                          },
                          "serveStale": {
                            "type": "number"
                          },
                          "bypassCookies": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "bypassHeaders": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "enabled",
                          "defaultTtl",
                          "serveStale"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "ssl",
                      "forceSsl",
                      "templates"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "live",
                      "redirect",
                      "missing"
                    ]
                  },
                  "redirectTarget": {
                    "type": "string",
                    "nullable": true
                  },
                  "redirectStatusCode": {
                    "type": "number",
                    "nullable": true
                  },
                  "sslStatus": {
                    "type": "object",
                    "properties": {
                      "state": {
                        "type": "string",
                        "enum": [
                          "error",
                          "secure",
                          "issuing",
                          "no_ssl",
                          "not_found",
                          "unavailable"
                        ]
                      },
                      "message": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "state",
                      "message"
                    ],
                    "additionalProperties": false
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "defaultTtl": {
                        "type": "number"
                      },
                      "serveStale": {
                        "type": "number"
                      },
                      "bypassCookies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "bypassHeaders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "enabled",
                      "defaultTtl",
                      "serveStale"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "routeId": {
                    "type": "string"
                  },
                  "imageOptimization": {
                    "type": "object",
                    "properties": {
                      "settings": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "mode": {
                            "type": "string",
                            "enum": [
                              "auto",
                              "params",
                              "both"
                            ]
                          },
                          "formats": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "avif",
                                "webp"
                              ]
                            }
                          },
                          "quality": {
                            "type": "number"
                          },
                          "saveDataQuality": {
                            "type": "number"
                          },
                          "avifSpeed": {
                            "type": "number"
                          },
                          "clientHints": {
                            "type": "boolean"
                          },
                          "maxWidth": {
                            "type": "number"
                          },
                          "maxHeight": {
                            "type": "number"
                          },
                          "allowedWidths": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          },
                          "maxSourceBytes": {
                            "type": "number"
                          },
                          "maxPixels": {
                            "type": "number"
                          },
                          "urlPrefix": {
                            "type": "string"
                          },
                          "avifMaxPixels": {
                            "type": "number"
                          },
                          "minSavings": {
                            "type": "number"
                          },
                          "allowUpscale": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "enabled",
                          "mode",
                          "formats",
                          "quality",
                          "saveDataQuality",
                          "avifSpeed",
                          "clientHints",
                          "maxWidth",
                          "maxHeight",
                          "allowedWidths",
                          "maxSourceBytes",
                          "maxPixels",
                          "urlPrefix",
                          "avifMaxPixels",
                          "minSavings",
                          "allowUpscale"
                        ],
                        "additionalProperties": false,
                        "nullable": true
                      },
                      "syncStatus": {
                        "type": "string",
                        "enum": [
                          "pending",
                          "active",
                          "error"
                        ],
                        "nullable": true
                      },
                      "syncError": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "settings",
                      "syncStatus",
                      "syncError"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "globalHostname": {
                    "type": "string",
                    "nullable": true
                  },
                  "globalHostnameKind": {
                    "type": "string",
                    "enum": [
                      "primary",
                      "alias"
                    ],
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "hostname",
                  "port",
                  "protocol",
                  "publicPort",
                  "tunnelUrl",
                  "proxySiteId",
                  "httpConfig",
                  "kind",
                  "redirectTarget",
                  "redirectStatusCode",
                  "sslStatus",
                  "cache",
                  "routeId",
                  "imageOptimization",
                  "globalHostname",
                  "globalHostnameKind"
                ],
                "additionalProperties": false
              }
            },
            "globalNamesAvailable": {
              "type": "boolean"
            },
            "customDomains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "wildcardPrefix": {
                    "type": "string",
                    "nullable": true
                  },
                  "port": {
                    "type": "string",
                    "nullable": true
                  },
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "error",
                      "verified"
                    ]
                  },
                  "verificationFqdn": {
                    "type": "string",
                    "nullable": true
                  },
                  "verificationToken": {
                    "type": "string",
                    "nullable": true
                  },
                  "lastError": {
                    "type": "string",
                    "nullable": true
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "live",
                      "redirect",
                      "missing"
                    ]
                  },
                  "redirectTarget": {
                    "type": "string",
                    "nullable": true
                  },
                  "redirectStatusCode": {
                    "type": "number",
                    "nullable": true
                  },
                  "sslStatus": {
                    "type": "object",
                    "properties": {
                      "state": {
                        "type": "string",
                        "enum": [
                          "error",
                          "secure",
                          "issuing",
                          "no_ssl",
                          "not_found",
                          "unavailable"
                        ]
                      },
                      "message": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "state",
                      "message"
                    ],
                    "additionalProperties": false
                  },
                  "cache": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "defaultTtl": {
                        "type": "number"
                      },
                      "serveStale": {
                        "type": "number"
                      },
                      "bypassCookies": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "bypassHeaders": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "enabled",
                      "defaultTtl",
                      "serveStale"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  },
                  "imageOptimization": {
                    "type": "object",
                    "properties": {
                      "settings": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "mode": {
                            "type": "string",
                            "enum": [
                              "auto",
                              "params",
                              "both"
                            ]
                          },
                          "formats": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "avif",
                                "webp"
                              ]
                            }
                          },
                          "quality": {
                            "type": "number"
                          },
                          "saveDataQuality": {
                            "type": "number"
                          },
                          "avifSpeed": {
                            "type": "number"
                          },
                          "clientHints": {
                            "type": "boolean"
                          },
                          "maxWidth": {
                            "type": "number"
                          },
                          "maxHeight": {
                            "type": "number"
                          },
                          "allowedWidths": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          },
                          "maxSourceBytes": {
                            "type": "number"
                          },
                          "maxPixels": {
                            "type": "number"
                          },
                          "urlPrefix": {
                            "type": "string"
                          },
                          "avifMaxPixels": {
                            "type": "number"
                          },
                          "minSavings": {
                            "type": "number"
                          },
                          "allowUpscale": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "enabled",
                          "mode",
                          "formats",
                          "quality",
                          "saveDataQuality",
                          "avifSpeed",
                          "clientHints",
                          "maxWidth",
                          "maxHeight",
                          "allowedWidths",
                          "maxSourceBytes",
                          "maxPixels",
                          "urlPrefix",
                          "avifMaxPixels",
                          "minSavings",
                          "allowUpscale"
                        ],
                        "additionalProperties": false,
                        "nullable": true
                      },
                      "syncStatus": {
                        "type": "string",
                        "enum": [
                          "pending",
                          "active",
                          "error"
                        ],
                        "nullable": true
                      },
                      "syncError": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "settings",
                      "syncStatus",
                      "syncError"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "id",
                  "domainName",
                  "wildcardPrefix",
                  "port",
                  "ssl",
                  "forceSsl",
                  "templates",
                  "status",
                  "verificationFqdn",
                  "verificationToken",
                  "lastError",
                  "kind",
                  "redirectTarget",
                  "redirectStatusCode",
                  "sslStatus",
                  "cache",
                  "imageOptimization"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "projectId",
            "containerId",
            "containerName",
            "regionId",
            "expectedCnameTarget",
            "suggestedPorts",
            "portSuggestions",
            "domainAccess",
            "availableOwnedDomains",
            "publicEndpoints",
            "globalNamesAvailable",
            "customDomains"
          ],
          "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": {
        "projectId": "string",
        "containerId": "string",
        "containerName": "string",
        "regionId": "string",
        "expectedCnameTarget": "string",
        "suggestedPorts": [
          0
        ],
        "portSuggestions": [
          {
            "port": 0,
            "protocol": "string",
            "source": "domain",
            "confidence": "open"
          }
        ],
        "domainAccess": {
          "isProjectOwner": true,
          "canAttachOwnerDomains": true
        },
        "availableOwnedDomains": [
          {
            "id": "string",
            "domainName": "string",
            "status": "pending",
            "verificationFqdn": "string",
            "verificationToken": "string",
            "lastError": "string",
            "containerId": "string",
            "port": "string",
            "ssl": true,
            "forceSsl": true,
            "templates": [
              "string"
            ],
            "cache": {
              "enabled": true,
              "defaultTtl": 0,
              "serveStale": 0,
              "bypassCookies": [
                "string"
              ],
              "bypassHeaders": [
                "string"
              ]
            }
          }
        ],
        "publicEndpoints": [
          {
            "id": "string",
            "hostname": "string",
            "port": 0,
            "protocol": "http",
            "publicPort": 0,
            "tunnelUrl": "string",
            "proxySiteId": "string",
            "httpConfig": {
              "ssl": true,
              "forceSsl": true,
              "templates": [
                "basic-security"
              ],
              "extraConfig": "string",
              "proxySetHeader": null,
              "cloudflareEnabled": true,
              "cache": {
                "enabled": true,
                "defaultTtl": 0,
                "serveStale": 0,
                "bypassCookies": [
                  "string"
                ],
                "bypassHeaders": [
                  "string"
                ]
              }
            },
            "kind": "live",
            "redirectTarget": "string",
            "redirectStatusCode": 0,
            "sslStatus": {
              "state": "error",
              "message": "string"
            },
            "cache": {
              "enabled": true,
              "defaultTtl": 0,
              "serveStale": 0,
              "bypassCookies": [
                "string"
              ],
              "bypassHeaders": [
                "string"
              ]
            },
            "routeId": "string",
            "imageOptimization": {
              "settings": {
                "enabled": true,
                "mode": "auto",
                "formats": [
                  "avif"
                ],
                "quality": 0,
                "saveDataQuality": 0,
                "avifSpeed": 0,
                "clientHints": true,
                "maxWidth": 0,
                "maxHeight": 0,
                "allowedWidths": [
                  0
                ],
                "maxSourceBytes": 0,
                "maxPixels": 0,
                "urlPrefix": "string",
                "avifMaxPixels": 0,
                "minSavings": 0,
                "allowUpscale": true
              },
              "syncStatus": "pending",
              "syncError": "string"
            },
            "globalHostname": "string",
            "globalHostnameKind": "primary"
          }
        ],
        "globalNamesAvailable": true,
        "customDomains": [
          {
            "id": "string",
            "domainName": "string",
            "wildcardPrefix": "string",
            "port": "string",
            "ssl": true,
            "forceSsl": true,
            "templates": [
              "string"
            ],
            "status": "pending",
            "verificationFqdn": "string",
            "verificationToken": "string",
            "lastError": "string",
            "kind": "live",
            "redirectTarget": "string",
            "redirectStatusCode": 0,
            "sslStatus": {
              "state": "error",
              "message": "string"
            },
            "cache": {
              "enabled": true,
              "defaultTtl": 0,
              "serveStale": 0,
              "bypassCookies": [
                "string"
              ],
              "bypassHeaders": [
                "string"
              ]
            },
            "imageOptimization": {
              "settings": {
                "enabled": true,
                "mode": "auto",
                "formats": [
                  "avif"
                ],
                "quality": 0,
                "saveDataQuality": 0,
                "avifSpeed": 0,
                "clientHints": true,
                "maxWidth": 0,
                "maxHeight": 0,
                "allowedWidths": [
                  0
                ],
                "maxSourceBytes": 0,
                "maxPixels": 0,
                "urlPrefix": "string",
                "avifMaxPixels": 0,
                "minSavings": 0,
                "allowUpscale": true
              },
              "syncStatus": "pending",
              "syncError": "string"
            }
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate a new load balancer groupDetails +/api/v1/projects/:projectId/load-balancers/create

Creates a new load balancer group for the project with a name, balancing algorithm (round robin, least connections, or IP hash), health-check path/interval, and active flag.

  • The group starts with no targets or domains attached.
  • Targets and domains must be added via separate endpoints before traffic can flow.
  • Requires the project's network:manage permission.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
descriptionstringNo
algorithmround_robin | least_conn | ip_hash | weighted_round_robin | weighted_least_conn | weighted_ip_hash | random | weighted_randomNo
healthcheckPathstringNo
healthcheckIntervalSecnumberNo
activebooleanNo
cacheEnabledbooleanNo
cacheDefaultTtlnumberNo
cacheServeStalenumberNo
cacheCacheControlbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "algorithm": {
      "type": "string",
      "enum": [
        "round_robin",
        "least_conn",
        "ip_hash",
        "weighted_round_robin",
        "weighted_least_conn",
        "weighted_ip_hash",
        "random",
        "weighted_random"
      ]
    },
    "healthcheckPath": {
      "type": "string"
    },
    "healthcheckIntervalSec": {
      "type": "number"
    },
    "active": {
      "type": "boolean"
    },
    "cacheEnabled": {
      "type": "boolean"
    },
    "cacheDefaultTtl": {
      "type": "number"
    },
    "cacheServeStale": {
      "type": "number"
    },
    "cacheCacheControl": {
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string",
              "nullable": true
            },
            "algorithm": {
              "type": "string"
            },
            "healthcheckPath": {
              "type": "string"
            },
            "healthcheckIntervalSec": {
              "type": "number"
            },
            "active": {
              "type": "boolean"
            },
            "cacheEnabled": {
              "type": "boolean"
            },
            "cacheDefaultTtl": {
              "type": "number"
            },
            "cacheServeStale": {
              "type": "number"
            },
            "cacheCacheControl": {
              "type": "boolean"
            },
            "targets": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "containerId": {
                    "type": "string"
                  },
                  "port": {
                    "type": "number"
                  },
                  "weight": {
                    "type": "number"
                  },
                  "containerName": {
                    "type": "string"
                  },
                  "containerStatus": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "containerId",
                  "port",
                  "weight",
                  "containerName",
                  "containerStatus"
                ],
                "additionalProperties": false
              }
            },
            "domains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "redirectTargetDomain": {
                    "type": "string",
                    "nullable": true
                  },
                  "status": {
                    "type": "string"
                  },
                  "lastError": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "domainName",
                  "ssl",
                  "forceSsl",
                  "templates",
                  "redirectTargetDomain",
                  "status",
                  "lastError"
                ],
                "additionalProperties": false
              }
            },
            "customDomains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainId": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "domainId",
                  "domainName",
                  "status"
                ],
                "additionalProperties": false
              }
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "projectId",
            "name",
            "description",
            "algorithm",
            "healthcheckPath",
            "healthcheckIntervalSec",
            "active",
            "cacheEnabled",
            "cacheDefaultTtl",
            "cacheServeStale",
            "cacheCacheControl",
            "targets",
            "domains",
            "customDomains",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "id": "string",
        "projectId": "string",
        "name": "string",
        "description": "string",
        "algorithm": "string",
        "healthcheckPath": "string",
        "healthcheckIntervalSec": 0,
        "active": true,
        "cacheEnabled": true,
        "cacheDefaultTtl": 0,
        "cacheServeStale": 0,
        "cacheCacheControl": true,
        "targets": [
          {
            "id": "string",
            "containerId": "string",
            "port": 0,
            "weight": 0,
            "containerName": "string",
            "containerStatus": "string"
          }
        ],
        "domains": [
          {
            "id": "string",
            "domainName": "string",
            "ssl": true,
            "forceSsl": true,
            "templates": [
              "string"
            ],
            "redirectTargetDomain": "string",
            "status": "string",
            "lastError": "string"
          }
        ],
        "customDomains": [
          {
            "id": "string",
            "domainId": "string",
            "domainName": "string",
            "status": "string"
          }
        ],
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTGenerate an available hubfly.app domain nameDetails +/api/v1/projects/:projectId/load-balancers/generate-domain

Given a base name, sanitizes it and generates an available candidate hubfly.app subdomain (e.g. <base>-ln-<random>.eu1.hubfly.app).

  • Retries with new random suffixes on collision, falling back to a random adjective-noun name after repeated collisions.
  • Only returns an available domain string; it does not reserve or create anything.
  • The caller must still attach the returned domain via the domain-create endpoint.
  • Requires authentication; does not check load balancer ownership.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
baseNamestringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "baseName": {
      "type": "string"
    }
  },
  "required": [
    "baseName"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "domain": {
              "type": "string"
            }
          },
          "required": [
            "domain"
          ],
          "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": {
        "domain": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList all load balancer groups for a projectDetails +/api/v1/projects/:projectId/load-balancers

Returns every load balancer group belonging to the project, each including its full set of targets (with live container name/status), hubfly-managed domains, and attached custom domains.

  • Requires the project's network:manage permission.
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"
              },
              "projectId": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string",
                "nullable": true
              },
              "algorithm": {
                "type": "string"
              },
              "healthcheckPath": {
                "type": "string"
              },
              "healthcheckIntervalSec": {
                "type": "number"
              },
              "active": {
                "type": "boolean"
              },
              "cacheEnabled": {
                "type": "boolean"
              },
              "cacheDefaultTtl": {
                "type": "number"
              },
              "cacheServeStale": {
                "type": "number"
              },
              "cacheCacheControl": {
                "type": "boolean"
              },
              "targets": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "containerId": {
                      "type": "string"
                    },
                    "port": {
                      "type": "number"
                    },
                    "weight": {
                      "type": "number"
                    },
                    "containerName": {
                      "type": "string"
                    },
                    "containerStatus": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "containerId",
                    "port",
                    "weight",
                    "containerName",
                    "containerStatus"
                  ],
                  "additionalProperties": false
                }
              },
              "domains": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "domainName": {
                      "type": "string"
                    },
                    "ssl": {
                      "type": "boolean"
                    },
                    "forceSsl": {
                      "type": "boolean"
                    },
                    "templates": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "redirectTargetDomain": {
                      "type": "string",
                      "nullable": true
                    },
                    "status": {
                      "type": "string"
                    },
                    "lastError": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "id",
                    "domainName",
                    "ssl",
                    "forceSsl",
                    "templates",
                    "redirectTargetDomain",
                    "status",
                    "lastError"
                  ],
                  "additionalProperties": false
                }
              },
              "customDomains": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "domainId": {
                      "type": "string"
                    },
                    "domainName": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "domainId",
                    "domainName",
                    "status"
                  ],
                  "additionalProperties": false
                }
              },
              "createdAt": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "projectId",
              "name",
              "description",
              "algorithm",
              "healthcheckPath",
              "healthcheckIntervalSec",
              "active",
              "cacheEnabled",
              "cacheDefaultTtl",
              "cacheServeStale",
              "cacheCacheControl",
              "targets",
              "domains",
              "customDomains",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": [
        {
          "id": "string",
          "projectId": "string",
          "name": "string",
          "description": "string",
          "algorithm": "string",
          "healthcheckPath": "string",
          "healthcheckIntervalSec": 0,
          "active": true,
          "cacheEnabled": true,
          "cacheDefaultTtl": 0,
          "cacheServeStale": 0,
          "cacheCacheControl": true,
          "targets": [
            {
              "id": "string",
              "containerId": "string",
              "port": 0,
              "weight": 0,
              "containerName": "string",
              "containerStatus": "string"
            }
          ],
          "domains": [
            {
              "id": "string",
              "domainName": "string",
              "ssl": true,
              "forceSsl": true,
              "templates": [
                "string"
              ],
              "redirectTargetDomain": "string",
              "status": "string",
              "lastError": "string"
            }
          ],
          "customDomains": [
            {
              "id": "string",
              "domainId": "string",
              "domainName": "string",
              "status": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTAttach a verified custom domain to a load balancerDetails +/api/v1/projects/:projectId/load-balancers/:lbId/custom-domains/attach

Attaches one of the caller's already-verified custom domains to a load balancer group, applying SSL/force-SSL and firewall template settings.

  • If the domain is currently attached to a different container or load balancer, the call fails with a transfer-required error unless approveTransfer is set.
  • When approveTransfer is set, the domain is moved from its old attachment to this group.
  • Requires network:manage permission on the project.
  • The domain must belong to the caller and be in verified status.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
domainIdstringYes
sslbooleanNo
forceSslbooleanNo
wildcardPrefixstringNo
templatesstring[]No
approveTransferbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "domainId": {
      "type": "string"
    },
    "ssl": {
      "type": "boolean"
    },
    "forceSsl": {
      "type": "boolean"
    },
    "wildcardPrefix": {
      "type": "string"
    },
    "templates": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "approveTransfer": {
      "type": "boolean"
    }
  },
  "required": [
    "domainId"
  ],
  "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"
            },
            "transferred": {
              "type": "boolean"
            }
          },
          "required": [
            "success",
            "transferred"
          ],
          "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,
        "transferred": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDelete a load balancer groupDetails +/api/v1/projects/:projectId/load-balancers/:lbId/delete

Deletes a load balancer group along with its targets and domains.

  • All of the group's hubfly-managed domains stop being served.
  • Deletion proceeds even if a domain fails to be cleaned up.
  • This action is irreversible.
  • Requires network:manage permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
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"
      }
    }
POSTAdd a hubfly-managed domain to a load balancerDetails +/api/v1/projects/:projectId/load-balancers/:lbId/domains/create

Adds a new domain (SSL, force-SSL, and firewall template settings included) to a load balancer group so it starts receiving traffic.

  • Requires the group to already have at least one target configured.
  • Returns a 409 if there are no targets yet or the domain name is already in use anywhere.
  • Requires network:manage permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
domainNamestringYes
sslbooleanNo
forceSslbooleanNo
templatesstring[]No
Complete request schema
{
  "type": "object",
  "properties": {
    "domainName": {
      "type": "string"
    },
    "ssl": {
      "type": "boolean"
    },
    "forceSsl": {
      "type": "boolean"
    },
    "templates": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "domainName"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "groupId": {
              "type": "string"
            },
            "domainName": {
              "type": "string"
            },
            "ssl": {
              "type": "boolean"
            },
            "forceSsl": {
              "type": "boolean"
            },
            "templates": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "redirectTargetDomain": {
              "type": "string",
              "nullable": true
            },
            "status": {
              "type": "string"
            },
            "lastError": {
              "type": "string",
              "nullable": true
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "groupId",
            "domainName",
            "ssl",
            "forceSsl",
            "templates",
            "redirectTargetDomain",
            "status",
            "lastError",
            "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",
        "groupId": "string",
        "domainName": "string",
        "ssl": true,
        "forceSsl": true,
        "templates": [
          "string"
        ],
        "redirectTargetDomain": "string",
        "status": "string",
        "lastError": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETERemove a domain from a load balancerDetails +/api/v1/projects/:projectId/load-balancers/:lbId/domains/:domainId/delete

Deletes a domain from a load balancer group, stopping traffic to that hostname.

  • The domain record is removed even if it can't be fully cleaned up downstream.
  • Refuses to delete a hubfly.app-managed domain if it is the group's last remaining active hubfly.app domain, to avoid leaving the load balancer unreachable.
  • Requires network:manage permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
domainIdpathYesstring—
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"
      }
    }
POSTConfigure a redirect for a load balancer domainDetails +/api/v1/projects/:projectId/load-balancers/:lbId/domains/:domainId/redirect

Turns an existing load balancer domain into a redirect (HTTP 302) pointing at a given target domain, using HTTPS or HTTP depending on the ssl flag.

  • Replaces any existing routing previously configured for that hostname.
  • Requires network:manage permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
domainIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
targetDomainstringYes
sslbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "targetDomain": {
      "type": "string"
    },
    "ssl": {
      "type": "boolean"
    }
  },
  "required": [
    "targetDomain"
  ],
  "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"
            }
          },
          "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"
      }
    }
PUTUpdate a load balancer domain's SSL/template settingsDetails +/api/v1/projects/:projectId/load-balancers/:lbId/domains/:domainId/update

Updates an existing load balancer domain's SSL, force-SSL, and firewall template settings.

  • Changes take effect immediately on the live route.
  • Requires network:manage permission on the project.
  • The domain must belong to the specified load balancer group.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
domainIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
sslbooleanNo
forceSslbooleanNo
templatesstring[]No
Complete request schema
{
  "type": "object",
  "properties": {
    "ssl": {
      "type": "boolean"
    },
    "forceSsl": {
      "type": "boolean"
    },
    "templates": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            }
          },
          "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"
      }
    }
GETGet a single load balancer group's detailsDetails +/api/v1/projects/:projectId/load-balancers/:lbId

Returns the full detail of one load balancer group, including its targets (with live container name/status), hubfly-managed domains, and attached custom domains.

  • Returns null if the group does not exist.
  • Requires the project's network:manage permission.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string",
              "nullable": true
            },
            "algorithm": {
              "type": "string"
            },
            "healthcheckPath": {
              "type": "string"
            },
            "healthcheckIntervalSec": {
              "type": "number"
            },
            "active": {
              "type": "boolean"
            },
            "cacheEnabled": {
              "type": "boolean"
            },
            "cacheDefaultTtl": {
              "type": "number"
            },
            "cacheServeStale": {
              "type": "number"
            },
            "cacheCacheControl": {
              "type": "boolean"
            },
            "targets": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "containerId": {
                    "type": "string"
                  },
                  "port": {
                    "type": "number"
                  },
                  "weight": {
                    "type": "number"
                  },
                  "containerName": {
                    "type": "string"
                  },
                  "containerStatus": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "containerId",
                  "port",
                  "weight",
                  "containerName",
                  "containerStatus"
                ],
                "additionalProperties": false
              }
            },
            "domains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "ssl": {
                    "type": "boolean"
                  },
                  "forceSsl": {
                    "type": "boolean"
                  },
                  "templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "redirectTargetDomain": {
                    "type": "string",
                    "nullable": true
                  },
                  "status": {
                    "type": "string"
                  },
                  "lastError": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "domainName",
                  "ssl",
                  "forceSsl",
                  "templates",
                  "redirectTargetDomain",
                  "status",
                  "lastError"
                ],
                "additionalProperties": false
              }
            },
            "customDomains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "domainId": {
                    "type": "string"
                  },
                  "domainName": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "domainId",
                  "domainName",
                  "status"
                ],
                "additionalProperties": false
              }
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "projectId",
            "name",
            "description",
            "algorithm",
            "healthcheckPath",
            "healthcheckIntervalSec",
            "active",
            "cacheEnabled",
            "cacheDefaultTtl",
            "cacheServeStale",
            "cacheCacheControl",
            "targets",
            "domains",
            "customDomains",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false,
          "nullable": true
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "id": "string",
        "projectId": "string",
        "name": "string",
        "description": "string",
        "algorithm": "string",
        "healthcheckPath": "string",
        "healthcheckIntervalSec": 0,
        "active": true,
        "cacheEnabled": true,
        "cacheDefaultTtl": 0,
        "cacheServeStale": 0,
        "cacheCacheControl": true,
        "targets": [
          {
            "id": "string",
            "containerId": "string",
            "port": 0,
            "weight": 0,
            "containerName": "string",
            "containerStatus": "string"
          }
        ],
        "domains": [
          {
            "id": "string",
            "domainName": "string",
            "ssl": true,
            "forceSsl": true,
            "templates": [
              "string"
            ],
            "redirectTargetDomain": "string",
            "status": "string",
            "lastError": "string"
          }
        ],
        "customDomains": [
          {
            "id": "string",
            "domainId": "string",
            "domainName": "string",
            "status": "string"
          }
        ],
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRe-sync a load balancer's domains to the proxyDetails +/api/v1/projects/:projectId/load-balancers/:lbId/sync

Forces all of a load balancer group's domains to be re-applied to routing, re-registering routes and targets from the group's current configuration.

  • Useful for recovering from routing drift or a failed automatic sync.
  • Syncing normally happens automatically after target/domain changes, so this is mainly for manual recovery.
  • Requires network:manage permission on the project.
  • Fails if the load balancer group does not exist.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "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"
      }
    }
POSTAdd a container as a load balancer targetDetails +/api/v1/projects/:projectId/load-balancers/:lbId/targets/create

Adds a container (with a container port and optional weight, default 1) as a backend target of a load balancer group.

  • Traffic starts routing to the new target automatically once added.
  • The container must belong to the same project as the load balancer.
  • Requires network:manage permission on the project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
containerIdstringYes
portnumberYes
weightnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "containerId": {
      "type": "string"
    },
    "port": {
      "type": "number"
    },
    "weight": {
      "type": "number"
    }
  },
  "required": [
    "containerId",
    "port"
  ],
  "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"
            }
          },
          "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"
      }
    }
DELETERemove a target from a load balancerDetails +/api/v1/projects/:projectId/load-balancers/:lbId/targets/:targetId/delete

Removes a container target from a load balancer group, stopping traffic from being routed to it.

  • Requires network:manage permission on the project.
  • Returns a 404 if the target does not belong to the specified group.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
targetIdpathYesstring—
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"
      }
    }
PUTUpdate a load balancer target's port or weightDetails +/api/v1/projects/:projectId/load-balancers/:lbId/targets/:targetId/update

Updates the container port and/or traffic weight of an existing load balancer target.

  • Changes take effect on live traffic routing automatically.
  • Requires network:manage permission on the project.
  • Returns a 404 if the target does not belong to the specified group.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—
targetIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
portnumberNo
weightnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "port": {
      "type": "number"
    },
    "weight": {
      "type": "number"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            }
          },
          "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"
      }
    }
PUTUpdate a load balancer group's settingsDetails +/api/v1/projects/:projectId/load-balancers/:lbId/update

Updates a load balancer group's name, description, algorithm, health-check path/interval, and/or active flag.

  • New settings take effect on live routing automatically.
  • Requires network:manage permission on the project.
  • Returns a 404 if the group does not exist.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
lbIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringNo
descriptionstringNo
algorithmround_robin | least_conn | ip_hash | weighted_round_robin | weighted_least_conn | weighted_ip_hash | random | weighted_randomNo
healthcheckPathstringNo
healthcheckIntervalSecnumberNo
activebooleanNo
cacheEnabledbooleanNo
cacheDefaultTtlnumberNo
cacheServeStalenumberNo
cacheCacheControlbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "nullable": true
    },
    "algorithm": {
      "type": "string",
      "enum": [
        "round_robin",
        "least_conn",
        "ip_hash",
        "weighted_round_robin",
        "weighted_least_conn",
        "weighted_ip_hash",
        "random",
        "weighted_random"
      ]
    },
    "healthcheckPath": {
      "type": "string"
    },
    "healthcheckIntervalSec": {
      "type": "number"
    },
    "active": {
      "type": "boolean"
    },
    "cacheEnabled": {
      "type": "boolean"
    },
    "cacheDefaultTtl": {
      "type": "number"
    },
    "cacheServeStale": {
      "type": "number"
    },
    "cacheCacheControl": {
      "type": "boolean"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "const": true,
              "type": "boolean"
            }
          },
          "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"
      }
    }
GETList the caller's reserved TCP/UDP portsDetails +/api/v1/projects/:projectId/ports

Lists all port reservations owned by the authenticated user, including the reserved host port range, protocol, mapping status, and which container/port it's currently mapped to, if any.

  • Returns reservations across all of the caller's projects, not just the one in the request path.
  • Requires authentication only.
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"
              },
              "userId": {
                "type": "string"
              },
              "projectId": {
                "type": "string"
              },
              "regionId": {
                "type": "string"
              },
              "hostPortStart": {
                "type": "number"
              },
              "hostPortEnd": {
                "type": "number"
              },
              "protocol": {
                "type": "string",
                "enum": [
                  "both",
                  "tcp",
                  "udp"
                ]
              },
              "containerId": {
                "type": "string",
                "nullable": true
              },
              "containerPort": {
                "type": "number",
                "nullable": true
              },
              "label": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "reserved",
                  "released"
                ]
              },
              "mappedAt": {
                "type": "string",
                "nullable": true
              },
              "createdAt": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "userId",
              "projectId",
              "regionId",
              "hostPortStart",
              "hostPortEnd",
              "protocol",
              "containerId",
              "containerPort",
              "label",
              "status",
              "mappedAt",
              "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",
          "userId": "string",
          "projectId": "string",
          "regionId": "string",
          "hostPortStart": 0,
          "hostPortEnd": 0,
          "protocol": "both",
          "containerId": "string",
          "containerPort": 0,
          "label": "string",
          "status": "active",
          "mappedAt": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTReserve a block of host ports in a regionDetails +/api/v1/projects/:projectId/ports/reserve

Reserves a contiguous block of 1-10 host ports (TCP, UDP, or both) in the 20000-30000 range for a region.

  • A free block is chosen automatically, retrying briefly if needed.
  • Each user has a global cap of 10 reserved ports across all their reservations.
  • Returns a 400 if the requested count would exceed that limit.
  • Returns a 503 if no free contiguous block can be found.
  • Requires authentication.
  • The reservation is not mapped to any container until a separate map call is made.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
regionIdstringYes
portCountnumberYes
protocolboth | tcp | udpYes
labelstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "regionId": {
      "type": "string"
    },
    "portCount": {
      "type": "number"
    },
    "protocol": {
      "type": "string",
      "enum": [
        "both",
        "tcp",
        "udp"
      ]
    },
    "label": {
      "type": "string"
    }
  },
  "required": [
    "regionId",
    "portCount",
    "protocol"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "userId": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "regionId": {
              "type": "string"
            },
            "hostPortStart": {
              "type": "number"
            },
            "hostPortEnd": {
              "type": "number"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "both",
                "tcp",
                "udp"
              ]
            },
            "containerId": {
              "type": "string",
              "nullable": true
            },
            "containerPort": {
              "type": "number",
              "nullable": true
            },
            "label": {
              "type": "string",
              "nullable": true
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "reserved",
                "released"
              ]
            },
            "mappedAt": {
              "type": "string",
              "nullable": true
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "userId",
            "projectId",
            "regionId",
            "hostPortStart",
            "hostPortEnd",
            "protocol",
            "containerId",
            "containerPort",
            "label",
            "status",
            "mappedAt",
            "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",
        "userId": "string",
        "projectId": "string",
        "regionId": "string",
        "hostPortStart": 0,
        "hostPortEnd": 0,
        "protocol": "both",
        "containerId": "string",
        "containerPort": 0,
        "label": "string",
        "status": "active",
        "mappedAt": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETERelease a port reservationDetails +/api/v1/projects/:projectId/ports/:reservationId

Deletes a port reservation owned by the caller, freeing its host port range for reuse.

  • Returns a 409 if the reservation is currently mapped to a container; it must be unmapped first.
  • Requires the reservation to belong to the authenticated user.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
reservationIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "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"
      }
    }
POSTMap a reserved host port to a container portDetails +/api/v1/projects/:projectId/ports/:reservationId/map

Maps one host port from a reservation (defaulting to the start of the reserved range, or a specific port within that range) to a given container's internal port.

  • Marks the reservation as active once mapped.
  • Fails if the container doesn't belong to the same project as the reservation.
  • Fails if the chosen host port is outside the reserved range.
  • Fails if that host port is already mapped on the container.
  • Requires the reservation to belong to the authenticated user.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
reservationIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
containerIdstringYes
containerPortnumberYes
hostPortnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "containerId": {
      "type": "string"
    },
    "containerPort": {
      "type": "number"
    },
    "hostPort": {
      "type": "number"
    }
  },
  "required": [
    "containerId",
    "containerPort"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "userId": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "regionId": {
              "type": "string"
            },
            "hostPortStart": {
              "type": "number"
            },
            "hostPortEnd": {
              "type": "number"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "both",
                "tcp",
                "udp"
              ]
            },
            "containerId": {
              "type": "string",
              "nullable": true
            },
            "containerPort": {
              "type": "number",
              "nullable": true
            },
            "label": {
              "type": "string",
              "nullable": true
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "reserved",
                "released"
              ]
            },
            "mappedAt": {
              "type": "string",
              "nullable": true
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "userId",
            "projectId",
            "regionId",
            "hostPortStart",
            "hostPortEnd",
            "protocol",
            "containerId",
            "containerPort",
            "label",
            "status",
            "mappedAt",
            "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",
        "userId": "string",
        "projectId": "string",
        "regionId": "string",
        "hostPortStart": 0,
        "hostPortEnd": 0,
        "protocol": "both",
        "containerId": "string",
        "containerPort": 0,
        "label": "string",
        "status": "active",
        "mappedAt": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTUnmap a host port from its containerDetails +/api/v1/projects/:projectId/ports/:reservationId/unmap

Removes a specific host port's mapping from whichever container currently has it, defaulting to the reservation's starting host port if none is specified.

  • The reservation reverts to reserved status once no ports in its range remain mapped.
  • Requires the reservation to belong to the authenticated user.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
reservationIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
hostPortnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "hostPort": {
      "type": "number"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "userId": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "regionId": {
              "type": "string"
            },
            "hostPortStart": {
              "type": "number"
            },
            "hostPortEnd": {
              "type": "number"
            },
            "protocol": {
              "type": "string",
              "enum": [
                "both",
                "tcp",
                "udp"
              ]
            },
            "containerId": {
              "type": "string",
              "nullable": true
            },
            "containerPort": {
              "type": "number",
              "nullable": true
            },
            "label": {
              "type": "string",
              "nullable": true
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "reserved",
                "released"
              ]
            },
            "mappedAt": {
              "type": "string",
              "nullable": true
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "userId",
            "projectId",
            "regionId",
            "hostPortStart",
            "hostPortEnd",
            "protocol",
            "containerId",
            "containerPort",
            "label",
            "status",
            "mappedAt",
            "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",
        "userId": "string",
        "projectId": "string",
        "regionId": "string",
        "hostPortStart": 0,
        "hostPortEnd": 0,
        "protocol": "both",
        "containerId": "string",
        "containerPort": 0,
        "label": "string",
        "status": "active",
        "mappedAt": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList the caller's reserved subdomainsDetails +/api/v1/projects/:projectId/subdomains

Lists all subdomain reservations owned by the authenticated user, including the resolved hostname pattern, target port, wildcard flag, and proxy/SSL status.

  • Returns reservations across all of the caller's projects, not just the one in the request path.
  • Requires authentication only.
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"
              },
              "userId": {
                "type": "string"
              },
              "projectId": {
                "type": "string"
              },
              "containerId": {
                "type": "string",
                "nullable": true
              },
              "boxId": {
                "type": "string",
                "nullable": true
              },
              "regionId": {
                "type": "string"
              },
              "subdomain": {
                "type": "string"
              },
              "pattern": {
                "type": "string"
              },
              "targetPort": {
                "type": "number"
              },
              "isWildcard": {
                "type": "boolean"
              },
              "proxySiteId": {
                "type": "string",
                "nullable": true
              },
              "sslMode": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "active",
                  "error",
                  "released",
                  "dns_pending"
                ]
              },
              "createdAt": {
                "type": "string"
              },
              "updatedAt": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "userId",
              "projectId",
              "containerId",
              "boxId",
              "regionId",
              "subdomain",
              "pattern",
              "targetPort",
              "isWildcard",
              "proxySiteId",
              "sslMode",
              "status",
              "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",
          "userId": "string",
          "projectId": "string",
          "containerId": "string",
          "boxId": "string",
          "regionId": "string",
          "subdomain": "string",
          "pattern": "string",
          "targetPort": 0,
          "isWildcard": true,
          "proxySiteId": "string",
          "sslMode": "string",
          "status": "pending",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTReserve a hubfly.app subdomain for a containerDetails +/api/v1/projects/:projectId/subdomains/reserve

Reserves a subdomain (optionally as a wildcard, e.g. *.name.eu1.hubfly.app) under the project's region and points it at a specific container and target port, with automatic TLS.

  • Fails if the subdomain name is invalid or already taken in the region.
  • Fails if the container doesn't belong to the project.
  • Fails if the container has no running, reachable instance yet — it must be deployed and running first.
  • Requires authentication.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
containerIdstringYes
subdomainstringYes
isWildcardbooleanYes
targetPortnumberYes
Complete request schema
{
  "type": "object",
  "properties": {
    "containerId": {
      "type": "string"
    },
    "subdomain": {
      "type": "string"
    },
    "isWildcard": {
      "type": "boolean"
    },
    "targetPort": {
      "type": "number"
    }
  },
  "required": [
    "containerId",
    "subdomain",
    "isWildcard",
    "targetPort"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "userId": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "containerId": {
              "type": "string",
              "nullable": true
            },
            "boxId": {
              "type": "string",
              "nullable": true
            },
            "regionId": {
              "type": "string"
            },
            "subdomain": {
              "type": "string"
            },
            "pattern": {
              "type": "string"
            },
            "targetPort": {
              "type": "number"
            },
            "isWildcard": {
              "type": "boolean"
            },
            "proxySiteId": {
              "type": "string",
              "nullable": true
            },
            "sslMode": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "active",
                "error",
                "released",
                "dns_pending"
              ]
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "userId",
            "projectId",
            "containerId",
            "boxId",
            "regionId",
            "subdomain",
            "pattern",
            "targetPort",
            "isWildcard",
            "proxySiteId",
            "sslMode",
            "status",
            "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",
        "userId": "string",
        "projectId": "string",
        "containerId": "string",
        "boxId": "string",
        "regionId": "string",
        "subdomain": "string",
        "pattern": "string",
        "targetPort": 0,
        "isWildcard": true,
        "proxySiteId": "string",
        "sslMode": "string",
        "status": "pending",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETERelease a reserved subdomainDetails +/api/v1/projects/:projectId/subdomains/:subdomainId

Deletes a subdomain reservation owned by the caller, stopping routing to that hostname.

  • The reservation is removed even if the routing cleanup doesn't fully succeed.
  • Requires the reservation to belong to the authenticated user.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
subdomainIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "success": {
              "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"
      }
    }

Related guides

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