Cell API · Dashboard
Network security & tunnels
Control project network firewall, access, challenge and private tunnel features.
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
- Read the current project network and access configuration.
- Apply the narrowest firewall, access or challenge policy that allows the required traffic.
- Use tunnels for authorized private access and inspect logs when requests are denied.
Inspect project network
curl "https://api.hubfly.space/api/v1/projects/$PROJECT_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 (20)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
GETGet public-route identity access settingsDetails +/api/v1/projects/:projectId/network/access
Returns the selected project route and its identity-access policy, including login, API-key and allowlist settings.
- The route may be a container endpoint, custom domain or load-balancer domain.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
routeType | query | Yes | string | — |
routeId | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "route": { "type": "object", "properties": { "routeType": { "type": "string", "enum": [ "custom_domain", "box_gateway", "container_endpoint", "load_balancer_domain", "load_balancer_custom_domain" ] }, "routeId": { "type": "string" }, "hostname": { "type": "string" }, "source": { "type": "string", "enum": [ "custom", "hubfly", "load_balancer", "box_gateway", "load_balancer_custom" ] }, "label": { "type": "string" }, "containerId": { "type": "string", "nullable": true }, "containerName": { "type": "string", "nullable": true }, "port": { "type": "number", "nullable": true }, "groupId": { "type": "string", "nullable": true }, "groupName": { "type": "string", "nullable": true }, "policyId": { "type": "string", "nullable": true }, "policyEnabled": { "type": "boolean" }, "policyMode": { "type": "string", "enum": [ "off", "login", "api_key", "login_or_api_key" ] }, "firewallSupported": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string" } } }, "required": [ "routeType", "routeId", "hostname", "source", "label", "containerId", "containerName", "port", "groupId", "groupName", "policyId", "policyEnabled", "policyMode", "firewallSupported" ], "additionalProperties": false }, "policy": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "off", "login", "api_key", "login_or_api_key" ] }, "allowProjectRead": { "type": "boolean" }, "allowedUserIds": { "type": "array", "items": { "type": "string" } }, "allowedEmails": { "type": "array", "items": { "type": "string" } }, "allowedOrgRoles": { "type": "array", "items": { "type": "string" } }, "sessionTtlSeconds": { "type": "number" }, "apiKeyHeader": { "type": "string" }, "injectIdentityHeaders": { "type": "boolean" }, "bypassPaths": { "type": "array", "items": { "type": "string" } }, "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tokenPrefix": { "type": "string" }, "status": { "type": "string" }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "description": "Date string", "nullable": true }, "lastUsedAt": { "type": "string", "description": "Date string", "nullable": true }, "lastUsedIp": { "type": "string", "nullable": true }, "revokedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "name", "tokenPrefix", "status", "allowedPaths", "expiresAt", "lastUsedAt", "lastUsedIp", "revokedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "enabled", "mode", "allowProjectRead", "allowedUserIds", "allowedEmails", "allowedOrgRoles", "sessionTtlSeconds", "apiKeyHeader", "injectIdentityHeaders", "bypassPaths", "apiKeys" ], "additionalProperties": false }, "availableOrgRoles": { "type": "array", "items": { "type": "string" } } }, "required": [ "route", "policy", "availableOrgRoles" ], "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": { "route": { "routeType": "custom_domain", "routeId": "string", "hostname": "string", "source": "custom", "label": "string", "containerId": "string", "containerName": "string", "port": 0, "groupId": "string", "groupName": "string", "policyId": "string", "policyEnabled": true, "policyMode": "off", "firewallSupported": true, "hosts": [ "string" ] }, "policy": { "id": "string", "enabled": true, "mode": "off", "allowProjectRead": true, "allowedUserIds": [ "string" ], "allowedEmails": [ "string" ], "allowedOrgRoles": [ "string" ], "sessionTtlSeconds": 0, "apiKeyHeader": "string", "injectIdentityHeaders": true, "bypassPaths": [ "string" ], "apiKeys": [ { "id": "string", "name": "string", "tokenPrefix": "string", "status": "string", "allowedPaths": [ "string" ], "expiresAt": "string", "lastUsedAt": "string", "lastUsedIp": "string", "revokedAt": "string", "createdAt": "string", "updatedAt": "string" } ] }, "availableOrgRoles": [ "string" ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a route access API keyDetails +/api/v1/projects/:projectId/network/access/keys/create
Creates an API key for a route access policy and returns the raw key once.
- Store the raw key immediately; later responses expose only its prefix and metadata.
- Use allowed paths and an expiry when a key does not need full-route access.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
policyId | string | Yes |
name | string | Yes |
allowedPaths | string[] | No |
expiresAt | string | No |
Complete request schema
{
"type": "object",
"properties": {
"policyId": {
"type": "string"
},
"name": {
"type": "string"
},
"allowedPaths": {
"type": "array",
"items": {
"type": "string"
}
},
"expiresAt": {
"type": "string",
"nullable": true
}
},
"required": [
"policyId",
"name"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tokenPrefix": { "type": "string" }, "status": { "type": "string" }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "description": "Date string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "token": { "type": "string" } }, "required": [ "id", "name", "tokenPrefix", "status", "allowedPaths", "expiresAt", "createdAt", "token" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "name": "string", "tokenPrefix": "string", "status": "string", "allowedPaths": [ "string" ], "expiresAt": "string", "createdAt": "string", "token": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRevoke a route access API keyDetails +/api/v1/projects/:projectId/network/access/keys/revoke
Revokes one API key issued for a project route access policy.
- Revocation takes effect for future requests using the key.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
keyId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"keyId": {
"type": "string"
}
},
"required": [
"keyId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse 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" } }
GETList routes that can use identity accessDetails +/api/v1/projects/:projectId/network/access/routes
Lists project public routes and the organization roles available for route access policies.
- Use the route type and route ID from this response when updating a policy.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "routeType": { "type": "string" }, "routeId": { "type": "string" }, "hostname": { "type": "string" }, "source": { "type": "string" }, "label": { "type": "string" }, "containerId": { "type": "string", "nullable": true }, "containerName": { "type": "string", "nullable": true }, "port": { "type": "number", "nullable": true }, "groupId": { "type": "string", "nullable": true }, "groupName": { "type": "string", "nullable": true }, "policyId": { "type": "string", "nullable": true }, "policyEnabled": { "type": "boolean" }, "policyMode": { "type": "string" }, "firewallSupported": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string" } } }, "required": [ "routeType", "routeId", "hostname", "source", "label", "containerId", "containerName", "port", "groupId", "groupName", "policyId", "policyEnabled", "policyMode", "firewallSupported" ], "additionalProperties": false } }, "availableOrgRoles": { "type": "array", "items": { "type": "string" } } }, "required": [ "routes", "availableOrgRoles" ], "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": { "routes": [ { "routeType": "string", "routeId": "string", "hostname": "string", "source": "string", "label": "string", "containerId": "string", "containerName": "string", "port": 0, "groupId": "string", "groupName": "string", "policyId": "string", "policyEnabled": true, "policyMode": "string", "firewallSupported": true, "hosts": [ "string" ] } ], "availableOrgRoles": [ "string" ] }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTUpdate a public-route access policyDetails +/api/v1/projects/:projectId/network/access/update
Configures whether a public route requires Hubfly space login, an API key, or either, with optional user, email, role, header and bypass-path rules.
- Treat the supplied policy arrays as the complete desired lists.
- Choose bypass paths carefully; they remain public when the policy is enabled.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
routeType | custom_domain | box_gateway | container_endpoint | load_balancer_domain | load_balancer_custom_domain | Yes |
routeId | string | Yes |
config | object | Yes |
Complete request schema
{
"type": "object",
"properties": {
"routeType": {
"type": "string",
"enum": [
"custom_domain",
"box_gateway",
"container_endpoint",
"load_balancer_domain",
"load_balancer_custom_domain"
]
},
"routeId": {
"type": "string"
},
"config": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"off",
"login",
"api_key",
"login_or_api_key"
]
},
"allowProjectRead": {
"type": "boolean"
},
"allowedUserIds": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedEmails": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedOrgRoles": {
"type": "array",
"items": {
"type": "string"
}
},
"sessionTtlSeconds": {
"type": "number"
},
"apiKeyHeader": {
"type": "string"
},
"injectIdentityHeaders": {
"type": "boolean"
},
"bypassPaths": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"enabled",
"mode"
],
"additionalProperties": false
}
},
"required": [
"routeType",
"routeId",
"config"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "routeType": { "type": "string" }, "routeId": { "type": "string" }, "domainName": { "type": "string" }, "enabled": { "type": "boolean" }, "mode": { "type": "string" }, "allowProjectRead": { "type": "boolean" }, "allowedUserIds": { "type": "array", "items": { "type": "string" } }, "allowedEmails": { "type": "array", "items": { "type": "string" } }, "allowedOrgRoles": { "type": "array", "items": { "type": "string" } }, "sessionTtlSeconds": { "type": "number" }, "apiKeyHeader": { "type": "string" }, "injectIdentityHeaders": { "type": "boolean" }, "bypassPaths": { "type": "array", "items": { "type": "string" } }, "createdByUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "projectId", "routeType", "routeId", "domainName", "enabled", "mode", "allowProjectRead", "allowedUserIds", "allowedEmails", "allowedOrgRoles", "sessionTtlSeconds", "apiKeyHeader", "injectIdentityHeaders", "bypassPaths", "createdByUserId", "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", "routeType": "string", "routeId": "string", "domainName": "string", "enabled": true, "mode": "string", "allowProjectRead": true, "allowedUserIds": [ "string" ], "allowedEmails": [ "string" ], "allowedOrgRoles": [ "string" ], "sessionTtlSeconds": 0, "apiKeyHeader": "string", "injectIdentityHeaders": true, "bypassPaths": [ "string" ], "createdByUserId": "string", "createdAt": "string", "updatedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead challenge analyticsDetails +/api/v1/projects/:projectId/network/challenge/analytics
Summarize challenge outcomes for one domain over range (24h default, 7d or 30d): counts per result, solve rate, average proof latency and the top 10 challenged paths. Figures are computed from up to 200 sampled request logs; truncated is true when more requests exist.
- Requires the
network:manageproject permission.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domain | query | No | string | — |
gatewayId | query | No | string | — |
range | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "7d", "30d", "24h" ] }, "sampledRequests": { "type": "number" }, "counts": { "type": "object", "additionalProperties": { "type": "number" } }, "solveRate": { "type": "number", "nullable": true }, "wouldChallenge": { "type": "number" }, "unverifiedByAction": { "type": "object", "additionalProperties": { "type": "number" } }, "averageProofLatencyMs": { "type": "number", "nullable": true }, "topChallengedPaths": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "count": { "type": "number" } }, "required": [ "path", "count" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "range", "sampledRequests", "counts", "solveRate", "wouldChallenge", "unverifiedByAction", "averageProofLatencyMs", "topChallengedPaths", "truncated" ], "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": { "range": "7d", "sampledRequests": 0, "counts": null, "solveRate": 0, "wouldChallenge": 0, "unverifiedByAction": null, "averageProofLatencyMs": 0, "topChallengedPaths": [ { "path": "string", "count": 0 } ], "truncated": true }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead a route's challenge policyDetails +/api/v1/projects/:projectId/network/challenge
Return the Hubfly space Challenge policy for one route, identified by routeType and routeId, with its bypass keys (name, prefix, status, allowed paths, expiry and last use). Returns policy: null when the route has none.
- Requires the
network:manageproject permission. - Bypass key tokens are never returned here, only their prefix.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
routeType | query | Yes | string | — |
routeId | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "bypassKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tokenPrefix": { "type": "string" }, "status": { "type": "string" }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "description": "Date string", "nullable": true }, "lastUsedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "name", "tokenPrefix", "status", "allowedPaths", "expiresAt", "lastUsedAt", "createdAt" ], "additionalProperties": false } }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "widgetId": { "type": "string" }, "sitekey": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "clearanceLevel": { "type": "string", "enum": [ "none", "managed", "interactive" ] }, "appearance": { "type": "string", "enum": [ "always", "execute", "interaction-only" ] }, "strictRemoteip": { "type": "boolean" }, "secretRotatedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "widgetId", "sitekey", "actions", "clearanceLevel", "appearance", "strictRemoteip", "secretRotatedAt", "createdAt" ], "additionalProperties": false } }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "routeType": { "type": "string" }, "routeId": { "type": "string" }, "domainName": { "type": "string" }, "enabled": { "type": "boolean" }, "mode": { "type": "string" }, "policyRevision": { "type": "number" }, "clearanceTtlSeconds": { "type": "number" }, "failureMode": { "type": "string" }, "allowVerifiedCrawlers": { "type": "boolean" }, "protectedRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassCidrs": { "type": "array", "items": { "type": "string" } }, "injectHeaders": { "type": "boolean" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "logOnly": { "type": "boolean" }, "proxyCapabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "nullable": true }, "capabilitiesCheckedAt": { "type": "string", "description": "Date string", "nullable": true }, "edgeActions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "tokenHeader": { "type": "string" }, "formField": { "type": "string" }, "onMissing": { "type": "string", "enum": [ "block", "challenge", "log" ] }, "minLevel": { "type": "string", "enum": [ "managed", "interactive" ] }, "surgeThreshold": { "type": "number" }, "surgeCooldownSeconds": { "type": "number" } }, "required": [ "name", "path", "match", "onMissing" ], "additionalProperties": false } }, "feedbackRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "number" } }, "weight": { "type": "number" } }, "required": [ "id", "path", "match", "status", "weight" ], "additionalProperties": false } }, "corsAllowedOrigins": { "type": "array", "items": { "type": "string" } }, "syncStatus": { "type": "string" }, "syncError": { "type": "string", "nullable": true }, "syncAttempts": { "type": "number" }, "nextSyncAt": { "type": "string", "description": "Date string", "nullable": true }, "lastSyncedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdByUserId": { "type": "string", "nullable": true } }, "required": [ "bypassKeys", "widgets", "createdAt", "updatedAt", "id", "projectId", "routeType", "routeId", "domainName", "enabled", "mode", "policyRevision", "clearanceTtlSeconds", "failureMode", "allowVerifiedCrawlers", "protectedRules", "bypassRules", "bypassCidrs", "injectHeaders", "sensitivity", "logOnly", "proxyCapabilities", "capabilitiesCheckedAt", "edgeActions", "feedbackRules", "corsAllowedOrigins", "syncStatus", "syncError", "syncAttempts", "nextSyncAt", "lastSyncedAt", "createdByUserId" ], "additionalProperties": false, "nullable": true } }, "required": [ "policy" ], "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": { "policy": { "bypassKeys": [ { "id": "string", "name": "string", "tokenPrefix": "string", "status": "string", "allowedPaths": [ "string" ], "expiresAt": "string", "lastUsedAt": "string", "createdAt": "string" } ], "widgets": [ { "id": "string", "widgetId": "string", "sitekey": "string", "actions": [ "string" ], "clearanceLevel": "none", "appearance": "always", "strictRemoteip": true, "secretRotatedAt": "string", "createdAt": "string" } ], "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "routeType": "string", "routeId": "string", "domainName": "string", "enabled": true, "mode": "string", "policyRevision": 0, "clearanceTtlSeconds": 0, "failureMode": "string", "allowVerifiedCrawlers": true, "protectedRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassCidrs": [ "string" ], "injectHeaders": true, "sensitivity": "low", "logOnly": true, "proxyCapabilities": null, "capabilitiesCheckedAt": "string", "edgeActions": [ { "name": "string", "path": "string", "match": "exact", "methods": [ "string" ], "tokenHeader": "string", "formField": "string", "onMissing": "block", "minLevel": "managed", "surgeThreshold": 0, "surgeCooldownSeconds": 0 } ], "feedbackRules": [ { "id": "string", "path": "string", "match": "exact", "methods": [ "string" ], "status": [ 0 ], "weight": 0 } ], "corsAllowedOrigins": [ "string" ], "syncStatus": "string", "syncError": "string", "syncAttempts": 0, "nextSyncAt": "string", "lastSyncedAt": "string", "createdByUserId": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a challenge bypass keyDetails +/api/v1/projects/:projectId/network/challenge/keys/create
Create a bypass key for a challenge policy so trusted clients skip the challenge by sending it in the X-Hubfly space-Challenge-Key header. The full token is returned only in this response.
- Requires the
network:manageproject permission. - The
tokenis shown once; store it securely. Only itsprefixis visible later. - Up to 20 active keys per policy (
409 CHALLENGE_KEY_LIMIT);expiresAtmust be in the future (400 INVALID_EXPIRES_AT). allowedPathsentries must start with/(others are dropped);nameis trimmed to 64 characters.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
policyId | string | Yes |
name | string | Yes |
allowedPaths | string[] | No |
expiresAt | string | No |
Complete request schema
{
"type": "object",
"properties": {
"policyId": {
"type": "string"
},
"name": {
"type": "string"
},
"allowedPaths": {
"type": "array",
"items": {
"type": "string"
}
},
"expiresAt": {
"type": "string",
"nullable": true
}
},
"required": [
"policyId",
"name"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "token": { "type": "string" }, "allowedPaths": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "id", "name", "prefix", "token", "allowedPaths", "expiresAt" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "name": "string", "prefix": "string", "token": "string", "allowedPaths": [ "string" ], "expiresAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRevoke a challenge bypass keyDetails +/api/v1/projects/:projectId/network/challenge/keys/revoke
Revoke one bypass key of a challenge policy and push the updated policy to the route. Returns { "revoked": true }.
- Requires the
network:manageproject permission. - An unknown policy returns
404 NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
policyId | string | Yes |
keyId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"policyId": {
"type": "string"
},
"keyId": {
"type": "string"
}
},
"required": [
"policyId",
"keyId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "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": { "revoked": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRetry challenge policy syncDetails +/api/v1/projects/:projectId/network/challenge/retry
Push a challenge policy to its route again, for example after fixing TLS or Force HTTPS. Returns the policy with its new syncStatus and syncError.
- Requires the
network:manageproject permission. - An unknown policy returns
404 NOT_FOUND;503 CHALLENGE_DISABLEDwhere Hubfly space Challenge is not enabled.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
policyId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"policyId": {
"type": "string"
}
},
"required": [
"policyId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "routeType": { "type": "string" }, "routeId": { "type": "string" }, "domainName": { "type": "string" }, "enabled": { "type": "boolean" }, "mode": { "type": "string" }, "policyRevision": { "type": "number" }, "clearanceTtlSeconds": { "type": "number" }, "failureMode": { "type": "string" }, "allowVerifiedCrawlers": { "type": "boolean" }, "protectedRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassCidrs": { "type": "array", "items": { "type": "string" } }, "injectHeaders": { "type": "boolean" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "logOnly": { "type": "boolean" }, "proxyCapabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "nullable": true }, "capabilitiesCheckedAt": { "type": "string", "description": "Date string", "nullable": true }, "edgeActions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "tokenHeader": { "type": "string" }, "formField": { "type": "string" }, "onMissing": { "type": "string", "enum": [ "block", "challenge", "log" ] }, "minLevel": { "type": "string", "enum": [ "managed", "interactive" ] }, "surgeThreshold": { "type": "number" }, "surgeCooldownSeconds": { "type": "number" } }, "required": [ "name", "path", "match", "onMissing" ], "additionalProperties": false } }, "feedbackRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "number" } }, "weight": { "type": "number" } }, "required": [ "id", "path", "match", "status", "weight" ], "additionalProperties": false } }, "corsAllowedOrigins": { "type": "array", "items": { "type": "string" } }, "syncStatus": { "type": "string" }, "syncError": { "type": "string", "nullable": true }, "syncAttempts": { "type": "number" }, "nextSyncAt": { "type": "string", "description": "Date string", "nullable": true }, "lastSyncedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdByUserId": { "type": "string", "nullable": true } }, "required": [ "createdAt", "updatedAt", "id", "projectId", "routeType", "routeId", "domainName", "enabled", "mode", "policyRevision", "clearanceTtlSeconds", "failureMode", "allowVerifiedCrawlers", "protectedRules", "bypassRules", "bypassCidrs", "injectHeaders", "sensitivity", "logOnly", "proxyCapabilities", "capabilitiesCheckedAt", "edgeActions", "feedbackRules", "corsAllowedOrigins", "syncStatus", "syncError", "syncAttempts", "nextSyncAt", "lastSyncedAt", "createdByUserId" ], "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": { "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "routeType": "string", "routeId": "string", "domainName": "string", "enabled": true, "mode": "string", "policyRevision": 0, "clearanceTtlSeconds": 0, "failureMode": "string", "allowVerifiedCrawlers": true, "protectedRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassCidrs": [ "string" ], "injectHeaders": true, "sensitivity": "low", "logOnly": true, "proxyCapabilities": null, "capabilitiesCheckedAt": "string", "edgeActions": [ { "name": "string", "path": "string", "match": "exact", "methods": [ "string" ], "tokenHeader": "string", "formField": "string", "onMissing": "block", "minLevel": "managed", "surgeThreshold": 0, "surgeCooldownSeconds": 0 } ], "feedbackRules": [ { "id": "string", "path": "string", "match": "exact", "methods": [ "string" ], "status": [ 0 ], "weight": 0 } ], "corsAllowedOrigins": [ "string" ], "syncStatus": "string", "syncError": "string", "syncAttempts": 0, "nextSyncAt": "string", "lastSyncedAt": "string", "createdByUserId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList challenge-capable routesDetails +/api/v1/projects/:projectId/network/challenge/routes
List the project's managed HTTP routes (container domains, custom domains and load balancer domains) with their hostname and any Hubfly space Challenge policy attached to each.
- Requires the
network:manageproject permission.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "challengePolicy": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "routeType": { "type": "string" }, "routeId": { "type": "string" }, "domainName": { "type": "string" }, "enabled": { "type": "boolean" }, "mode": { "type": "string" }, "policyRevision": { "type": "number" }, "clearanceTtlSeconds": { "type": "number" }, "failureMode": { "type": "string" }, "allowVerifiedCrawlers": { "type": "boolean" }, "protectedRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassCidrs": { "type": "array", "items": { "type": "string" } }, "injectHeaders": { "type": "boolean" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "logOnly": { "type": "boolean" }, "proxyCapabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "nullable": true }, "capabilitiesCheckedAt": { "type": "string", "description": "Date string", "nullable": true }, "edgeActions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "tokenHeader": { "type": "string" }, "formField": { "type": "string" }, "onMissing": { "type": "string", "enum": [ "block", "challenge", "log" ] }, "minLevel": { "type": "string", "enum": [ "managed", "interactive" ] }, "surgeThreshold": { "type": "number" }, "surgeCooldownSeconds": { "type": "number" } }, "required": [ "name", "path", "match", "onMissing" ], "additionalProperties": false } }, "feedbackRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "number" } }, "weight": { "type": "number" } }, "required": [ "id", "path", "match", "status", "weight" ], "additionalProperties": false } }, "corsAllowedOrigins": { "type": "array", "items": { "type": "string" } }, "syncStatus": { "type": "string" }, "syncError": { "type": "string", "nullable": true }, "syncAttempts": { "type": "number" }, "nextSyncAt": { "type": "string", "description": "Date string", "nullable": true }, "lastSyncedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdByUserId": { "type": "string", "nullable": true } }, "required": [ "createdAt", "updatedAt", "id", "projectId", "routeType", "routeId", "domainName", "enabled", "mode", "policyRevision", "clearanceTtlSeconds", "failureMode", "allowVerifiedCrawlers", "protectedRules", "bypassRules", "bypassCidrs", "injectHeaders", "sensitivity", "logOnly", "proxyCapabilities", "capabilitiesCheckedAt", "edgeActions", "feedbackRules", "corsAllowedOrigins", "syncStatus", "syncError", "syncAttempts", "nextSyncAt", "lastSyncedAt", "createdByUserId" ], "additionalProperties": false, "nullable": true }, "routeType": { "type": "string", "enum": [ "custom_domain", "box_gateway", "container_endpoint", "load_balancer_domain", "load_balancer_custom_domain" ] }, "routeId": { "type": "string" }, "hostname": { "type": "string" }, "source": { "type": "string", "enum": [ "custom", "hubfly", "load_balancer", "box_gateway", "load_balancer_custom" ] }, "label": { "type": "string" }, "containerId": { "type": "string", "nullable": true }, "containerName": { "type": "string", "nullable": true }, "port": { "type": "number", "nullable": true }, "groupId": { "type": "string", "nullable": true }, "groupName": { "type": "string", "nullable": true }, "policyId": { "type": "string", "nullable": true }, "policyEnabled": { "type": "boolean" }, "policyMode": { "type": "string", "enum": [ "off", "login", "api_key", "login_or_api_key" ] }, "firewallSupported": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string" } } }, "required": [ "challengePolicy", "routeType", "routeId", "hostname", "source", "label", "containerId", "containerName", "port", "groupId", "groupName", "policyId", "policyEnabled", "policyMode", "firewallSupported" ], "additionalProperties": false } } }, "required": [ "routes" ], "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": { "routes": [ { "challengePolicy": { "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "routeType": "string", "routeId": "string", "domainName": "string", "enabled": true, "mode": "string", "policyRevision": 0, "clearanceTtlSeconds": 0, "failureMode": "string", "allowVerifiedCrawlers": true, "protectedRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassCidrs": [ "string" ], "injectHeaders": true, "sensitivity": "low", "logOnly": true, "proxyCapabilities": null, "capabilitiesCheckedAt": "string", "edgeActions": [ { "name": "string", "path": "string", "match": "exact", "methods": [ "string" ], "tokenHeader": "string", "formField": "string", "onMissing": "block", "minLevel": "managed", "surgeThreshold": 0, "surgeCooldownSeconds": 0 } ], "feedbackRules": [ { "id": "string", "path": "string", "match": "exact", "methods": [ "string" ], "status": [ 0 ], "weight": 0 } ], "corsAllowedOrigins": [ "string" ], "syncStatus": "string", "syncError": "string", "syncAttempts": 0, "nextSyncAt": "string", "lastSyncedAt": "string", "createdByUserId": "string" }, "routeType": "custom_domain", "routeId": "string", "hostname": "string", "source": "custom", "label": "string", "containerId": "string", "containerName": "string", "port": 0, "groupId": "string", "groupName": "string", "policyId": "string", "policyEnabled": true, "policyMode": "off", "firewallSupported": true, "hosts": [ "string" ] } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTUpdate a challenge policyDetails +/api/v1/projects/:projectId/network/challenge/update
Create or replace the Hubfly space Challenge policy of one route and push it to the route. Each update increments the policy revision; the returned policy's syncStatus is active, error or unsupported, with syncError explaining a failure.
- Requires the
network:manageproject permission. modeisalways(default),adaptive,sensitive_pathsorunder_attack;failureModeisrisk_based(default),fail_openorfail_closed;clearanceTtlSecondsis clamped to 300–86,400 (default 1,800).- Up to 64
protectedRulesand 64bypassRules(paths start with/, at most 256 characters) and up to 64bypassCidrs; violations return400. - Enabling requires active TLS and Force HTTPS on the route, otherwise the policy is saved with
syncStatuserror. - An unknown route returns
404 NOT_FOUND;503 CHALLENGE_DISABLEDwhere Hubfly space Challenge is not enabled.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
routeType | custom_domain | box_gateway | container_endpoint | load_balancer_domain | load_balancer_custom_domain | Yes |
routeId | string | Yes |
config | object | Yes |
Complete request schema
{
"type": "object",
"properties": {
"routeType": {
"type": "string",
"enum": [
"custom_domain",
"box_gateway",
"container_endpoint",
"load_balancer_domain",
"load_balancer_custom_domain"
]
},
"routeId": {
"type": "string"
},
"config": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"always",
"adaptive",
"sensitive_paths",
"under_attack"
]
},
"clearanceTtlSeconds": {
"type": "number"
},
"failureMode": {
"type": "string",
"enum": [
"risk_based",
"fail_open",
"fail_closed"
]
},
"allowVerifiedCrawlers": {
"type": "boolean"
},
"protectedRules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"match": {
"type": "string",
"enum": [
"exact",
"prefix"
]
},
"methods": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"path",
"match"
],
"additionalProperties": false
}
},
"bypassRules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"match": {
"type": "string",
"enum": [
"exact",
"prefix"
]
},
"methods": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"path",
"match"
],
"additionalProperties": false
}
},
"bypassCidrs": {
"type": "array",
"items": {
"type": "string"
}
},
"injectHeaders": {
"type": "boolean"
},
"sensitivity": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"nullable": true
},
"logOnly": {
"type": "boolean"
},
"edgeActions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"match": {
"type": "string",
"enum": [
"exact",
"prefix"
]
},
"name": {
"type": "string"
},
"methods": {
"type": "array",
"items": {
"type": "string"
}
},
"tokenHeader": {
"type": "string"
},
"formField": {
"type": "string"
},
"minLevel": {
"type": "string",
"enum": [
"managed",
"interactive"
]
},
"surgeThreshold": {
"type": "number"
},
"surgeCooldownSeconds": {
"type": "number"
},
"onMissing": {
"type": "string",
"enum": [
"block",
"challenge",
"log"
]
}
},
"required": [
"path",
"match",
"name"
],
"additionalProperties": false
}
},
"feedbackRules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"path": {
"type": "string"
},
"match": {
"type": "string",
"enum": [
"exact",
"prefix"
]
},
"methods": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "array",
"items": {
"type": "number"
}
},
"weight": {
"type": "number"
}
},
"required": [
"id",
"path",
"match",
"status",
"weight"
],
"additionalProperties": false
}
},
"corsAllowedOrigins": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"enabled"
],
"additionalProperties": false
}
},
"required": [
"routeType",
"routeId",
"config"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "routeType": { "type": "string" }, "routeId": { "type": "string" }, "domainName": { "type": "string" }, "enabled": { "type": "boolean" }, "mode": { "type": "string" }, "policyRevision": { "type": "number" }, "clearanceTtlSeconds": { "type": "number" }, "failureMode": { "type": "string" }, "allowVerifiedCrawlers": { "type": "boolean" }, "protectedRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassRules": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } } }, "required": [ "path", "match" ], "additionalProperties": false } }, "bypassCidrs": { "type": "array", "items": { "type": "string" } }, "injectHeaders": { "type": "boolean" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "logOnly": { "type": "boolean" }, "proxyCapabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "nullable": true }, "capabilitiesCheckedAt": { "type": "string", "description": "Date string", "nullable": true }, "edgeActions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "tokenHeader": { "type": "string" }, "formField": { "type": "string" }, "onMissing": { "type": "string", "enum": [ "block", "challenge", "log" ] }, "minLevel": { "type": "string", "enum": [ "managed", "interactive" ] }, "surgeThreshold": { "type": "number" }, "surgeCooldownSeconds": { "type": "number" } }, "required": [ "name", "path", "match", "onMissing" ], "additionalProperties": false } }, "feedbackRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "match": { "type": "string", "enum": [ "exact", "prefix" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "number" } }, "weight": { "type": "number" } }, "required": [ "id", "path", "match", "status", "weight" ], "additionalProperties": false } }, "corsAllowedOrigins": { "type": "array", "items": { "type": "string" } }, "syncStatus": { "type": "string" }, "syncError": { "type": "string", "nullable": true }, "syncAttempts": { "type": "number" }, "nextSyncAt": { "type": "string", "description": "Date string", "nullable": true }, "lastSyncedAt": { "type": "string", "description": "Date string", "nullable": true }, "createdByUserId": { "type": "string", "nullable": true } }, "required": [ "createdAt", "updatedAt", "id", "projectId", "routeType", "routeId", "domainName", "enabled", "mode", "policyRevision", "clearanceTtlSeconds", "failureMode", "allowVerifiedCrawlers", "protectedRules", "bypassRules", "bypassCidrs", "injectHeaders", "sensitivity", "logOnly", "proxyCapabilities", "capabilitiesCheckedAt", "edgeActions", "feedbackRules", "corsAllowedOrigins", "syncStatus", "syncError", "syncAttempts", "nextSyncAt", "lastSyncedAt", "createdByUserId" ], "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": { "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "routeType": "string", "routeId": "string", "domainName": "string", "enabled": true, "mode": "string", "policyRevision": 0, "clearanceTtlSeconds": 0, "failureMode": "string", "allowVerifiedCrawlers": true, "protectedRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassRules": [ { "path": "string", "match": "exact", "methods": [ "string" ] } ], "bypassCidrs": [ "string" ], "injectHeaders": true, "sensitivity": "low", "logOnly": true, "proxyCapabilities": null, "capabilitiesCheckedAt": "string", "edgeActions": [ { "name": "string", "path": "string", "match": "exact", "methods": [ "string" ], "tokenHeader": "string", "formField": "string", "onMissing": "block", "minLevel": "managed", "surgeThreshold": 0, "surgeCooldownSeconds": 0 } ], "feedbackRules": [ { "id": "string", "path": "string", "match": "exact", "methods": [ "string" ], "status": [ 0 ], "weight": 0 } ], "corsAllowedOrigins": [ "string" ], "syncStatus": "string", "syncError": "string", "syncAttempts": 0, "nextSyncAt": "string", "lastSyncedAt": "string", "createdByUserId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETGet firewall rules for a project domainDetails +/api/v1/projects/:projectId/network/firewall
Fetches the current firewall configuration for a specific hostname served by the project, including IP allow/deny rules, block rules for user agents/methods/paths, rate limiting, and custom rule templates.
- Requires network:manage permission on the project.
- Returns an empty/default configuration if the hostname has no site registered yet.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domain | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "ip_rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "allow", "deny" ] }, "value": { "type": "string" } }, "required": [ "action", "value" ], "additionalProperties": false } }, "block_rules": { "type": "object", "properties": { "user_agents": { "type": "array", "items": { "type": "string" } }, "methods": { "type": "array", "items": { "type": "string" } }, "paths": { "type": "array", "items": { "type": "string" } }, "path_methods": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [], "additionalProperties": false }, "rate_limit": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "rate": { "type": "number" }, "unit": { "type": "string", "enum": [ "r/s", "r/m" ] }, "burst": { "type": "number" } }, "required": [ "enabled", "rate", "unit" ], "additionalProperties": false }, "templates": { "type": "array", "items": { "type": "string" } }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } }, { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } } ], "nullable": true } } } }, "required": [], "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": { "ip_rules": [ { "action": "allow", "value": "string" } ], "block_rules": { "user_agents": [ "string" ], "methods": [ "string" ], "paths": [ "string" ], "path_methods": null }, "rate_limit": { "enabled": true, "rate": 0, "unit": "r/s", "burst": 0 }, "templates": [ "string" ], "rules": [ null ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTUpdate firewall rules for a project domainDetails +/api/v1/projects/:projectId/network/firewall/update
Replaces the firewall configuration (IP rules, block rules, rate limiting, templates, custom rules) for a given hostname.
- Returns a 404 if no site matches the hostname.
- Returns a 502 if the update could not be applied due to an unexpected upstream response.
- Requires network:manage permission on the project.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
domain | string | Yes |
config | object | Yes |
Complete request schema
{
"type": "object",
"properties": {
"domain": {
"type": "string"
},
"config": {
"type": "object",
"properties": {
"ip_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"value": {
"type": "string"
}
},
"required": [
"action",
"value"
],
"additionalProperties": false
}
},
"block_rules": {
"type": "object",
"properties": {
"user_agents": {
"type": "array",
"items": {
"type": "string"
}
},
"methods": {
"type": "array",
"items": {
"type": "string"
}
},
"paths": {
"type": "array",
"items": {
"type": "string"
}
},
"path_methods": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [],
"additionalProperties": false
},
"rate_limit": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"rate": {
"type": "number"
},
"unit": {
"type": "string",
"enum": [
"r/s",
"r/m"
]
},
"burst": {
"type": "number"
}
},
"required": [
"enabled",
"rate",
"unit"
],
"additionalProperties": false
},
"templates": {
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"const": false,
"type": "boolean"
},
{
"const": true,
"type": "boolean"
},
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"type": "array",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"const": false,
"type": "boolean"
},
{
"const": true,
"type": "boolean"
}
],
"nullable": true
}
},
{
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"const": false,
"type": "boolean"
},
{
"const": true,
"type": "boolean"
}
],
"nullable": true
}
}
],
"nullable": true
}
}
}
},
"required": [],
"additionalProperties": false
}
},
"required": [
"domain",
"config"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "ip_rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "allow", "deny" ] }, "value": { "type": "string" } }, "required": [ "action", "value" ], "additionalProperties": false } }, "block_rules": { "type": "object", "properties": { "user_agents": { "type": "array", "items": { "type": "string" } }, "methods": { "type": "array", "items": { "type": "string" } }, "paths": { "type": "array", "items": { "type": "string" } }, "path_methods": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [], "additionalProperties": false }, "rate_limit": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "rate": { "type": "number" }, "unit": { "type": "string", "enum": [ "r/s", "r/m" ] }, "burst": { "type": "number" } }, "required": [ "enabled", "rate", "unit" ], "additionalProperties": false }, "templates": { "type": "array", "items": { "type": "string" } }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } }, { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } } ], "nullable": true } } } }, "required": [], "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": { "ip_rules": [ { "action": "allow", "value": "string" } ], "block_rules": { "user_agents": [ "string" ], "methods": [ "string" ], "paths": [ "string" ], "path_methods": null }, "rate_limit": { "enabled": true, "rate": 0, "unit": "r/s", "burst": 0 }, "templates": [ "string" ], "rules": [ null ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETGet project network subnet and bandwidth infoDetails +/api/v1/projects/:projectId/network
Returns the project's private network details (subnet, gateway IP) and current ingress/egress bandwidth rates in Mbps.
- Returns all-null values if the project is hibernating/stopped or if the network can't be inspected right now.
- Requires the caller to have access to the project.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "subnet": { "type": "string", "nullable": true }, "gatewayIp": { "type": "string", "nullable": true }, "ingressMbps": { "type": "number", "nullable": true }, "egressMbps": { "type": "number", "nullable": true } }, "required": [ "subnet", "gatewayIp", "ingressMbps", "egressMbps" ], "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": { "subnet": "string", "gatewayIp": "string", "ingressMbps": 0, "egressMbps": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETQuery proxy access logs for a project domainDetails +/api/v1/projects/:projectId/network/logs
Retrieves recent HTTP access log entries for a given hostname, with optional filtering by search text, status code, HTTP method, client IP, and pagination (limit/offset).
- Requires network:manage permission on the project.
- Returns a 502 if the logs cannot be retrieved successfully.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
domain | query | Yes | string | — |
limit | query | No | number | — |
cursor | query | No | string | — |
search | query | No | string | — |
requestId | query | No | string | — |
status | query | No | number | — |
statusClass | query | No | string | — |
method | query | No | string | — |
clientIp | query | No | string | — |
identityResult | query | No | string | — |
identityPolicyId | query | No | string | — |
identityApiKeyId | query | No | string | — |
challengeResult | query | No | string | — |
challengePolicyId | query | No | string | — |
startTime | query | No | string | — |
endTime | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string" }, "site_id": { "type": "string" }, "timestamp": { "type": "string" }, "level": { "type": "string" }, "message": { "type": "string" }, "raw": { "type": "string" }, "remote_addr": { "type": "string" }, "request": { "type": "string" }, "client_ip": { "type": "string" }, "status": { "type": "number" }, "method": { "type": "string" }, "host": { "type": "string" }, "path": { "type": "string" }, "query": { "type": "string" }, "protocol": { "type": "string" }, "upstream": { "type": "string" }, "latency_ms": { "type": "number" }, "bytes_sent": { "type": "number" }, "bytes_received": { "type": "number" }, "user_agent": { "type": "string" }, "referer": { "type": "string" }, "request_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "identity_policy_id": { "type": "string" }, "identity_result": { "type": "string" }, "identity_reason": { "type": "string" }, "identity_subject": { "type": "string" }, "identity_api_key_id": { "type": "string" }, "challenge_policy_id": { "type": "string" }, "challenge_result": { "type": "string" }, "challenge_reason": { "type": "string" }, "challenge_mode": { "type": "string" }, "challenge_risk": { "type": "string" }, "challenge_bypass_key_id": { "type": "string" }, "challenge_proof_latency_ms": { "type": "number" }, "challenge_clearance_age_seconds": { "type": "number" }, "client_solve_ms": { "type": "number" }, "challenge_score": { "type": "number" }, "challenge_level": { "type": "string" }, "challenge_would": { "type": "string" }, "challenge_reasons": { "type": "string" }, "challenge_bot": { "type": "string" }, "challenge_action": { "type": "string" }, "ja4": { "type": "string" }, "error": { "type": "string" } }, "required": [ "request_id", "timestamp" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "items", "nextCursor", "hasMore" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "request_id": "string", "site_id": "string", "timestamp": "string", "level": "string", "message": "string", "raw": "string", "remote_addr": "string", "request": "string", "client_ip": "string", "status": 0, "method": "string", "host": "string", "path": "string", "query": "string", "protocol": "string", "upstream": "string", "latency_ms": 0, "bytes_sent": 0, "bytes_received": 0, "user_agent": "string", "referer": "string", "request_headers": null, "identity_policy_id": "string", "identity_result": "string", "identity_reason": "string", "identity_subject": "string", "identity_api_key_id": "string", "challenge_policy_id": "string", "challenge_result": "string", "challenge_reason": "string", "challenge_mode": "string", "challenge_risk": "string", "challenge_bypass_key_id": "string", "challenge_proof_latency_ms": 0, "challenge_clearance_age_seconds": 0, "client_solve_ms": 0, "challenge_score": 0, "challenge_level": "string", "challenge_would": "string", "challenge_reasons": "string", "challenge_bot": "string", "challenge_action": "string", "ja4": "string", "error": "string" } ], "nextCursor": "string", "hasMore": true }, "meta": { "requestId": "string", "timestamp": "string" } }
GETGet an overview of all proxy routes for a projectDetails +/api/v1/projects/:projectId/network/proxy
Builds a consolidated view of every hostname the project is reachable on, combining hubfly-managed container ports and attached custom domains, each annotated with its live route status/kind and SSL state.
- Requires network:manage permission on the project.
- Returns a 404 if the project or its region cannot be resolved.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "projectId": { "type": "string" }, "projectName": { "type": "string" }, "regionId": { "type": "string" }, "reverseProxyReachable": { "type": "boolean" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "source": { "type": "string", "enum": [ "custom", "hubfly" ] }, "containerId": { "type": "string", "nullable": true }, "containerName": { "type": "string", "nullable": true }, "port": { "type": "number", "nullable": true }, "protocol": { "type": "string", "enum": [ "http", "tcp", "udp" ], "nullable": true }, "kind": { "type": "string", "enum": [ "live", "redirect", "missing" ] }, "routeTarget": { "type": "string", "nullable": true }, "sslEnabled": { "type": "boolean" }, "forceSsl": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "ready", "error", "missing" ] } }, "required": [ "id", "hostname", "source", "containerId", "containerName", "port", "protocol", "kind", "routeTarget", "sslEnabled", "forceSsl", "status" ], "additionalProperties": false } } }, "required": [ "projectId", "projectName", "regionId", "reverseProxyReachable", "domains" ], "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", "projectName": "string", "regionId": "string", "reverseProxyReachable": true, "domains": [ { "id": "string", "hostname": "string", "source": "custom", "containerId": "string", "containerName": "string", "port": 0, "protocol": "http", "kind": "live", "routeTarget": "string", "sslEnabled": true, "forceSsl": true, "status": "pending" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTOpen a HubTunnel session to a container portDetails +/api/v1/projects/:projectId/tunnels/create
Creates a short-lived tunnel session (a HubTunnel) that lets a client, typically the CLI, reach a specific port on a running container over a secure relay rather than through the public internet — used for things like debugging a private service without exposing it.
- Returns a one-time connect token and URL.
- Rate-limited per user.
- Subject to per-user and per-project limits on concurrent active tunnels.
- Defaults to a 1-hour time-to-live (minimum 5 minutes, maximum 24 hours).
- Requires the target container to be running.
- Requires the project's container:terminal permission.
- Allowed even while the project is hibernating.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
containerId | string | Yes |
targetPort | number | Yes |
localPort | number | No |
ttlSeconds | number | No |
Complete request schema
{
"type": "object",
"properties": {
"containerId": {
"type": "string"
},
"targetPort": {
"type": "number"
},
"localPort": {
"type": "number"
},
"ttlSeconds": {
"type": "number"
}
},
"required": [
"containerId",
"targetPort"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "tunnelId": { "type": "string" }, "targetContainerId": { "type": "string" }, "targetContainerName": { "type": "string" }, "targetPort": { "type": "number" }, "connectUrl": { "type": "string" }, "connectToken": { "type": "string" }, "protocolVersion": { "const": 1, "type": "number" }, "mode": { "const": "ports", "type": "string" }, "expiresAt": { "type": "string" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "targetId": { "type": "string" }, "containerId": { "type": "string" }, "containerName": { "type": "string" }, "runtimeId": { "type": "string" }, "targetPort": { "type": "number" }, "localPort": { "type": "number" } }, "required": [ "targetId", "containerId", "containerName", "runtimeId", "targetPort", "localPort" ], "additionalProperties": false } }, "limits": { "type": "object", "properties": { "maxStreams": { "type": "number" }, "idleTimeoutSeconds": { "type": "number" }, "maxDurationSeconds": { "type": "number" } }, "required": [ "maxStreams", "idleTimeoutSeconds", "maxDurationSeconds" ], "additionalProperties": false } }, "required": [ "tunnelId", "targetContainerId", "targetContainerName", "targetPort", "connectUrl", "connectToken", "protocolVersion", "mode", "expiresAt", "targets", "limits" ], "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": { "tunnelId": "string", "targetContainerId": "string", "targetContainerName": "string", "targetPort": 0, "connectUrl": "string", "connectToken": "string", "protocolVersion": 0, "mode": "string", "expiresAt": "string", "targets": [ { "targetId": "string", "containerId": "string", "containerName": "string", "runtimeId": "string", "targetPort": 0, "localPort": 0 } ], "limits": { "maxStreams": 0, "idleTimeoutSeconds": 0, "maxDurationSeconds": 0 } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList active/recent tunnel sessions for a projectDetails +/api/v1/projects/:projectId/tunnels
Lists the caller's tunnel sessions for the project that are still open or in a non-terminal state (pending, claimed, active, closing, error, or expired), including target container info, connection URL, byte counters, and stream counts.
- Expired sessions are cleaned up automatically before the list is returned.
- Requires the project's container:terminal permission.
- Only returns tunnels owned by the requesting user.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tunnelId": { "type": "string" }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "targetContainerId": { "type": "string", "nullable": true }, "targetContainerName": { "type": "string", "nullable": true }, "targetPort": { "type": "number" }, "mode": { "type": "string", "enum": [ "ports", "subnet" ] }, "status": { "type": "string", "enum": [ "pending", "closed", "active", "closing", "expired", "error", "claimed" ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "targetId": { "type": "string" }, "containerId": { "type": "string" }, "containerName": { "type": "string" }, "runtimeId": { "type": "string" }, "targetPort": { "type": "number" }, "localPort": { "type": "number" } }, "required": [ "targetId", "containerId", "containerName", "runtimeId", "targetPort", "localPort" ], "additionalProperties": false } }, "connectUrl": { "type": "string" }, "expiresAt": { "type": "string", "description": "Date string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "bytesSent": { "type": "string" }, "bytesReceived": { "type": "string" }, "streamsOpened": { "type": "number" }, "closeReason": { "type": "string", "nullable": true } }, "required": [ "id", "tunnelId", "projectId", "projectName", "targetContainerId", "targetContainerName", "targetPort", "mode", "status", "targets", "connectUrl", "expiresAt", "createdAt", "bytesSent", "bytesReceived", "streamsOpened", "closeReason" ], "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", "tunnelId": "string", "projectId": "string", "projectName": "string", "targetContainerId": "string", "targetContainerName": "string", "targetPort": 0, "mode": "ports", "status": "pending", "targets": [ { "targetId": "string", "containerId": "string", "containerName": "string", "runtimeId": "string", "targetPort": 0, "localPort": 0 } ], "connectUrl": "string", "expiresAt": "string", "createdAt": "string", "bytesSent": "string", "bytesReceived": "string", "streamsOpened": 0, "closeReason": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETEClose and remove a tunnel sessionDetails +/api/v1/projects/:projectId/tunnels/:tunnelId/delete
Closes a tunnel session, terminating the CLI-to-container relay.
- This action is irreversible; a new tunnel must be created to reconnect.
- Only the user who originally created the tunnel may delete it, even if other users have permission on the project.
- Requires the project's container:terminal permission.
- Returns a 404 if the tunnel doesn't belong to the given project.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
tunnelId | path | Yes | string | — |
Responses
200— Successful responseResponse 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" } }