Realtime API · Dashboard
Servers & lifecycle
Price, create and operate a realtime server: power, resize, upgrade, protect, delete, network allowlist and operations.
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.
Realtime servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the realtime server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the realtime permissions must hold that exact permission.
How to use these endpoints
- Get the hourly quote for the size, then create the server with
service: "realtime",quotedHourlyTotaland a uniqueidempotencyKey. PassinitialAppto create the first app in the same call. - Creation, power, resize and upgrade calls are asynchronous; poll the returned operation. A restart hands connections over in place; an upgrade interrupts service for about 10–20 seconds while clients reconnect.
- Read the connection details for the WebSocket host and app credentials to configure clients.
- The IP allowlist only guards the server HTTP API. WebSocket clients are never IP-restricted.
Create a realtime server with its first app
# The create call must repeat the current hourly quote.
QUOTE=$(curl -s "https://api.hubfly.space/api/v1/pricing/managed/estimate?cpu=0.25&memoryMib=512&storageGib=1" \
-H "Authorization: Bearer $HUBFLY_TOKEN" | jq '.data.hourly.total')
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"chat","service":"realtime","size":{"cpu":0.25,"memoryMib":512,"storageGib":1},"initialApp":{"name":"web"},"quotedHourlyTotal":'"$QUOTE"',"idempotencyKey":"create-chat-1"}'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.
GETRead the managed services catalogDetails +/api/v1/managed/catalog
Returns the managed services, database engines with their available versions and starting prices, size presets and limits, the allowlist and per-account instance limits, and realtime server settings. available is false when Hubfly space is not accepting new database instances.
- Requires a signed-in user or personal access token; no project permission is checked.
- Platform and sub-account keys are refused with
403 MACHINE_CREDENTIAL_UNSUPPORTED. - Deprecated engine versions are left out of the list.
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "database", "cache", "realtime", "stream" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "coming_soon" ] } }, "required": [ "id", "label", "description", "status" ], "additionalProperties": false } }, "engines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "postgresql", "mysql", "libsql" ] }, "label": { "type": "string" }, "shortLabel": { "type": "string" }, "description": { "type": "string" }, "minMemoryMib": { "type": "number" }, "transport": { "type": "string", "enum": [ "tcp", "https" ] }, "exportFormats": { "type": "array", "items": { "type": "string", "enum": [ "native", "sql" ] } }, "capabilities": { "type": "object", "properties": { "databases": { "type": "boolean" }, "users": { "type": "boolean" }, "tokens": { "type": "boolean" }, "query": { "type": "boolean" }, "schema": { "type": "boolean" }, "explorer": { "type": "boolean" }, "config": { "type": "boolean" }, "rawConfig": { "type": "boolean" }, "certificate": { "type": "boolean" }, "extensions": { "type": "boolean" }, "insights": { "type": "boolean" }, "sessions": { "type": "boolean" }, "shell": { "type": "boolean" }, "export": { "type": "boolean" }, "import": { "type": "boolean" } }, "required": [ "databases", "users", "tokens", "query", "schema", "explorer", "config", "rawConfig", "certificate", "extensions", "insights", "sessions", "shell", "export", "import" ], "additionalProperties": false }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "isDefault": { "type": "boolean" }, "lts": { "type": "boolean" }, "status": { "type": "string", "enum": [ "available", "preview", "deprecated" ] } }, "required": [ "id", "label", "isDefault", "lts", "status" ], "additionalProperties": false } }, "startingPrice": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false } }, "required": [ "id", "label", "shortLabel", "description", "minMemoryMib", "transport", "exportFormats", "capabilities", "versions", "startingPrice" ], "additionalProperties": false } }, "sizes": { "type": "object", "properties": { "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "cpu": { "type": "number" }, "memoryMib": { "type": "number" }, "description": { "type": "string" } }, "required": [ "id", "label", "cpu", "memoryMib", "description" ], "additionalProperties": false } }, "cpu": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" } }, "required": [ "min", "max", "step" ], "additionalProperties": false }, "memoryMib": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" } }, "required": [ "min", "max", "step" ], "additionalProperties": false }, "storageGib": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "required": [ "min", "max", "default" ], "additionalProperties": false } }, "required": [ "presets", "cpu", "memoryMib", "storageGib" ], "additionalProperties": false }, "maxAllowlistEntries": { "type": "number" }, "maxInstancesPerAccount": { "type": "number" }, "realtime": { "type": "object", "properties": { "available": { "type": "boolean" }, "engine": { "type": "object", "properties": { "id": { "const": "realtime", "type": "string" }, "label": { "type": "string" }, "shortLabel": { "type": "string" }, "description": { "type": "string" }, "minMemoryMib": { "type": "number" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": [ "available", "preview", "deprecated" ] } }, "required": [ "id", "label", "isDefault", "status" ], "additionalProperties": false } } }, "required": [ "id", "label", "shortLabel", "description", "minMemoryMib", "versions" ], "additionalProperties": false }, "sizes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "cpu": { "type": "number" }, "memoryMib": { "type": "number" }, "description": { "type": "string" }, "profile": { "type": "object", "properties": { "memoryMib": { "type": "number" }, "cpu": { "type": "number" }, "maxConnections": { "type": "number" }, "deliveriesPerSecond": { "type": "number" }, "publishesPerSecond": { "type": "number" }, "maxPayloadBytes": { "type": "number" }, "bandwidthMbps": { "type": "number" }, "historyMaxTtlSeconds": { "type": "number" }, "memoryLimitBytes": { "type": "number" } }, "required": [ "memoryMib", "cpu", "maxConnections", "deliveriesPerSecond", "publishesPerSecond", "maxPayloadBytes", "bandwidthMbps", "historyMaxTtlSeconds", "memoryLimitBytes" ], "additionalProperties": false }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false } }, "required": [ "id", "label", "cpu", "memoryMib", "description", "profile", "price" ], "additionalProperties": false } }, "storageGib": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "required": [ "min", "max", "default" ], "additionalProperties": false }, "startingPrice": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "maxAppsPerInstance": { "type": "number" }, "maxKeysPerApp": { "type": "number" }, "maxWebhooksPerApp": { "type": "number" }, "maxAllowedOrigins": { "type": "number" } }, "required": [ "maxAppsPerInstance", "maxKeysPerApp", "maxWebhooksPerApp", "maxAllowedOrigins" ], "additionalProperties": false }, "webhookEvents": { "type": "array", "items": { "type": "string" } }, "keyGraceSeconds": { "type": "number" }, "maxInstancesPerAccount": { "type": "number" } }, "required": [ "available", "engine", "sizes", "storageGib", "startingPrice", "limits", "webhookEvents", "keyGraceSeconds", "maxInstancesPerAccount" ], "additionalProperties": false }, "streams": { "type": "object", "properties": { "available": { "type": "boolean" }, "speedPresetsMbps": { "type": "array", "items": { "type": "number" } }, "speedMbps": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" }, "default": { "type": "number" } }, "required": [ "min", "max", "step", "default" ], "additionalProperties": false }, "processingMbps": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "required": [ "min", "max", "default" ], "additionalProperties": false }, "maxSpeedMbpsWithoutDeposit": { "type": "number" }, "freeSpeedMbps": { "type": "number" }, "maxInstancesPerAccount": { "type": "number" }, "startingPrice": { "type": "object", "properties": { "hourly": { "type": "object", "properties": { "speedMicroUsd": { "type": "number" }, "speedMicroUsdAfterFree": { "type": "number" } }, "required": [ "speedMicroUsd", "speedMicroUsdAfterFree" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "speedUsd": { "type": "number" }, "speedUsdAfterFree": { "type": "number" } }, "required": [ "speedUsd", "speedUsdAfterFree" ], "additionalProperties": false }, "freeSpeedMbps": { "type": "number" }, "pricing": { "type": "object", "properties": { "version": { "type": "number" }, "speedMicroUsdPerMbpsHour": { "type": "number" }, "processingMicroUsdPerMbpsHour": { "type": "number" }, "bandwidthMicroUsdPerGb": { "type": "number" }, "freeSpeedMbpsPerHour": { "type": "number" }, "freeProcessingMbpsHoursPerMonth": { "type": "number" }, "freeBandwidthGbPerMonth": { "type": "number" } }, "required": [ "version", "speedMicroUsdPerMbpsHour", "processingMicroUsdPerMbpsHour", "bandwidthMicroUsdPerGb", "freeSpeedMbpsPerHour", "freeProcessingMbpsHoursPerMonth", "freeBandwidthGbPerMonth" ], "additionalProperties": false } }, "required": [ "hourly", "monthly", "freeSpeedMbps", "pricing" ], "additionalProperties": false }, "pricing": { "type": "object", "properties": { "version": { "type": "number" }, "speedMicroUsdPerMbpsHour": { "type": "number" }, "processingMicroUsdPerMbpsHour": { "type": "number" }, "bandwidthMicroUsdPerGb": { "type": "number" }, "freeSpeedMbpsPerHour": { "type": "number" }, "freeProcessingMbpsHoursPerMonth": { "type": "number" }, "freeBandwidthGbPerMonth": { "type": "number" } }, "required": [ "version", "speedMicroUsdPerMbpsHour", "processingMicroUsdPerMbpsHour", "bandwidthMicroUsdPerGb", "freeSpeedMbpsPerHour", "freeProcessingMbpsHoursPerMonth", "freeBandwidthGbPerMonth" ], "additionalProperties": false } }, "required": [ "available", "speedPresetsMbps", "speedMbps", "processingMbps", "maxSpeedMbpsWithoutDeposit", "freeSpeedMbps", "maxInstancesPerAccount", "startingPrice", "pricing" ], "additionalProperties": false } }, "required": [ "available", "services", "engines", "sizes", "maxAllowlistEntries", "maxInstancesPerAccount", "realtime", "streams" ], "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": { "available": true, "services": [ { "id": "database", "label": "string", "description": "string", "status": "available" } ], "engines": [ { "id": "postgresql", "label": "string", "shortLabel": "string", "description": "string", "minMemoryMib": 0, "transport": "tcp", "exportFormats": [ "native" ], "capabilities": { "databases": true, "users": true, "tokens": true, "query": true, "schema": true, "explorer": true, "config": true, "rawConfig": true, "certificate": true, "extensions": true, "insights": true, "sessions": true, "shell": true, "export": true, "import": true }, "versions": [ { "id": "string", "label": "string", "isDefault": true, "lts": true, "status": "available" } ], "startingPrice": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } } } ], "sizes": { "presets": [ { "id": "string", "label": "string", "cpu": 0, "memoryMib": 0, "description": "string" } ], "cpu": { "min": 0, "max": 0, "step": 0 }, "memoryMib": { "min": 0, "max": 0, "step": 0 }, "storageGib": { "min": 0, "max": 0, "default": 0 } }, "maxAllowlistEntries": 0, "maxInstancesPerAccount": 0, "realtime": { "available": true, "engine": { "id": "string", "label": "string", "shortLabel": "string", "description": "string", "minMemoryMib": 0, "versions": [ { "id": "string", "label": "string", "isDefault": true, "status": "available" } ] }, "sizes": [ { "id": "string", "label": "string", "cpu": 0, "memoryMib": 0, "description": "string", "profile": { "memoryMib": 0, "cpu": 0, "maxConnections": 0, "deliveriesPerSecond": 0, "publishesPerSecond": 0, "maxPayloadBytes": 0, "bandwidthMbps": 0, "historyMaxTtlSeconds": 0, "memoryLimitBytes": 0 }, "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } } } ], "storageGib": { "min": 0, "max": 0, "default": 0 }, "startingPrice": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "limits": { "maxAppsPerInstance": 0, "maxKeysPerApp": 0, "maxWebhooksPerApp": 0, "maxAllowedOrigins": 0 }, "webhookEvents": [ "string" ], "keyGraceSeconds": 0, "maxInstancesPerAccount": 0 }, "streams": { "available": true, "speedPresetsMbps": [ 0 ], "speedMbps": { "min": 0, "max": 0, "step": 0, "default": 0 }, "processingMbps": { "min": 0, "max": 0, "default": 0 }, "maxSpeedMbpsWithoutDeposit": 0, "freeSpeedMbps": 0, "maxInstancesPerAccount": 0, "startingPrice": { "hourly": { "speedMicroUsd": 0, "speedMicroUsdAfterFree": 0 }, "monthly": { "speedUsd": 0, "speedUsdAfterFree": 0 }, "freeSpeedMbps": 0, "pricing": { "version": 0, "speedMicroUsdPerMbpsHour": 0, "processingMicroUsdPerMbpsHour": 0, "bandwidthMicroUsdPerGb": 0, "freeSpeedMbpsPerHour": 0, "freeProcessingMbpsHoursPerMonth": 0, "freeBandwidthGbPerMonth": 0 } }, "pricing": { "version": 0, "speedMicroUsdPerMbpsHour": 0, "processingMicroUsdPerMbpsHour": 0, "bandwidthMicroUsdPerGb": 0, "freeSpeedMbpsPerHour": 0, "freeProcessingMbpsHoursPerMonth": 0, "freeBandwidthGbPerMonth": 0 } } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETEstimate a managed instance priceDetails +/api/v1/pricing/managed/estimate
Returns the hourly and monthly price of a running managed instance of the given size, split into compute, storage and management fee, in USD.
- No authentication required. Calls made with a platform or sub-account key are refused with
403 MACHINE_CREDENTIAL_UNSUPPORTED. cpumust be 0.25-8,memoryMib256-32768 andstorageGib1-500; otherwise400 MANAGED_INVALID_SIZE.- Use the returned
hourly.totalasquotedHourlyTotalwhen you create or resize an instance.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
cpu | query | Yes | number | — |
memoryMib | query | Yes | number | — |
storageGib | query | Yes | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "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": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead managed services ratesDetails +/api/v1/pricing/managed
Returns the rates used to price managed instances: per-vCPU-hour, per-GiB-hour memory and storage rates, the management fee rate applied to compute, the currency and the hours counted per month.
- No authentication required. Calls made with a platform or sub-account key are refused with
403 MACHINE_CREDENTIAL_UNSUPPORTED.
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "cpuPerVcpuHour": { "type": "number" }, "memoryPerGibHour": { "type": "number" }, "storagePerGibHour": { "type": "number" }, "managementFeeRate": { "const": 0.3, "type": "number" } }, "required": [ "currency", "hoursPerMonth", "cpuPerVcpuHour", "memoryPerGibHour", "storagePerGibHour", "managementFeeRate" ], "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": { "currency": "string", "hoursPerMonth": 0, "cpuPerVcpuHour": 0, "memoryPerGibHour": 0, "storagePerGibHour": 0, "managementFeeRate": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a managed instanceDetails +/api/v1/projects/:projectId/managed/instances/create
Creates a managed database (service: "database", the default) or a realtime server (service: "realtime") in the project and starts provisioning it. Hubfly space places the instance in the project's region. A realtime server is created with a first app (named production by default) and its key.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). - Asynchronous: returns an
operationId; pollGET /api/v1/projects/:projectId/managed/instances/:instanceId/operations/:operationIduntil it ends. idempotencyKey(1-128 characters) is required; repeating a key in the same project returns the original instance and operation.quotedHourlyTotalmust match the current price fromGET /api/v1/pricing/managed/estimate, or the call fails with409 MANAGED_PRICE_CHANGED.- Errors:
409 MANAGED_NAME_TAKEN,409 MANAGED_INSTANCE_LIMIT,402 INSUFFICIENT_BALANCE,503 MANAGED_SERVICES_UNAVAILABLE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
service | database | realtime | stream | No |
engine | realtime | postgresql | mysql | libsql | stream | No |
version | string | No |
size | object | No |
publicAccess | boolean | No |
allowlist | object[] | No |
defaultDatabaseName | string | No |
adminUsername | string | No |
initialApp | object | No |
stream | object | No |
quotedHourlyTotal | number | Yes |
idempotencyKey | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"service": {
"type": "string",
"enum": [
"database",
"realtime",
"stream"
]
},
"engine": {
"type": "string",
"enum": [
"realtime",
"postgresql",
"mysql",
"libsql",
"stream"
]
},
"version": {
"type": "string"
},
"size": {
"type": "object",
"properties": {
"cpu": {
"type": "number"
},
"memoryMib": {
"type": "number"
},
"storageGib": {
"type": "number"
}
},
"required": [
"cpu",
"memoryMib"
],
"additionalProperties": false
},
"publicAccess": {
"type": "boolean"
},
"allowlist": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cidr": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"cidr"
],
"additionalProperties": false
}
},
"defaultDatabaseName": {
"type": "string"
},
"adminUsername": {
"type": "string"
},
"initialApp": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"settings": {
"type": "object",
"properties": {
"allowedOrigins": {
"type": "array",
"items": {
"type": "string"
}
},
"clientEvents": {
"type": "boolean"
},
"subscriptionCountEvents": {
"type": "boolean"
},
"requireUserAuthentication": {
"type": "boolean"
},
"maxConnections": {
"type": "number"
},
"maxChannelsPerConnection": {
"type": "number"
},
"maxPresenceMembers": {
"type": "number"
},
"maxMessageBytes": {
"type": "number"
},
"maxPublishesPerSecond": {
"type": "number"
},
"maxClientEventsPerSecond": {
"type": "number"
},
"history": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"off",
"memory",
"durable"
]
},
"ttlSeconds": {
"type": "number"
},
"maxMessages": {
"type": "number"
}
},
"required": [],
"additionalProperties": false
},
"sessions": {
"type": "object",
"properties": {
"detachTtlSeconds": {
"type": "number"
}
},
"required": [],
"additionalProperties": false
},
"offlineQueue": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"ttlSeconds": {
"type": "number"
},
"maxMessages": {
"type": "number"
}
},
"required": [],
"additionalProperties": false
},
"encryption": {
"type": "string",
"enum": [
"off",
"optional",
"required"
]
},
"inspectorPayloadPreview": {
"type": "boolean"
}
},
"required": [],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
},
"stream": {
"type": "object",
"properties": {
"speedMbps": {
"type": "number"
},
"processingMbps": {
"type": "number"
},
"timezone": {
"type": "string"
},
"firstInput": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"kind": {
"const": "push",
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
},
"required": [
"speedMbps"
],
"additionalProperties": false
},
"quotedHourlyTotal": {
"type": "number"
},
"idempotencyKey": {
"type": "string"
}
},
"required": [
"name",
"quotedHourlyTotal",
"idempotencyKey"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "instance": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "service": { "type": "string", "enum": [ "database", "realtime", "stream" ] }, "engine": { "type": "string", "enum": [ "realtime", "postgresql", "mysql", "libsql", "stream" ] }, "engineLabel": { "type": "string" }, "version": { "type": "string" }, "versionLabel": { "type": "string" }, "engineVersion": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "failed", "deleted", "provisioning", "stopped", "running", "deleting", "starting", "stopping", "restarting", "updating" ] }, "statusReason": { "type": "string", "nullable": true }, "size": { "type": "object", "properties": { "cpu": { "type": "number" }, "memoryMib": { "type": "number" }, "storageGib": { "type": "number" } }, "required": [ "cpu", "memoryMib", "storageGib" ], "additionalProperties": false }, "storageUsedBytes": { "type": "number", "nullable": true }, "storageTotalBytes": { "type": "number", "nullable": true }, "publicAccess": { "type": "boolean" }, "allowlistCount": { "type": "number" }, "deletionProtection": { "type": "boolean" }, "pendingRestart": { "type": "boolean" }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "activeOperation": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "stepIndex": { "type": "number" }, "stepCount": { "type": "number" }, "stepLabel": { "type": "string", "nullable": true } }, "required": [ "id", "kind", "status", "stepIndex", "stepCount", "stepLabel" ], "additionalProperties": false, "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "stream": { "type": "object", "properties": { "host": { "type": "string" }, "speedMbps": { "type": "number" }, "processingMbps": { "type": "number" }, "webrtcSessions": { "type": "number" }, "timezone": { "type": "string" }, "sync": { "type": "object", "properties": { "generation": { "type": "number" }, "appliedGeneration": { "type": "number" }, "lastSyncedAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true } }, "required": [ "generation", "appliedGeneration", "lastSyncedAt", "lastError" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "allowed", "reason" ], "additionalProperties": false }, "ingest": { "type": "object", "properties": { "rtmp": { "type": "string" }, "rtmps": { "type": "string" }, "srt": { "type": "string" }, "whipBase": { "type": "string" }, "icecastBase": { "type": "string" } }, "required": [ "rtmp", "rtmps", "srt", "whipBase", "icecastBase" ], "additionalProperties": false }, "live": { "type": "object", "properties": { "inputsLive": { "type": "number" }, "channelsLive": { "type": "number" }, "viewers": { "type": "number" }, "egressMbps": { "type": "number" }, "at": { "type": "string" } }, "required": [ "inputsLive", "channelsLive", "viewers", "egressMbps", "at" ], "additionalProperties": false, "nullable": true }, "price": { "type": "object", "properties": { "speedMicroUsdPerHour": { "type": "number" }, "speedUsdPerMonth": { "type": "number" } }, "required": [ "speedMicroUsdPerHour", "speedUsdPerMonth" ], "additionalProperties": false } }, "required": [ "host", "speedMbps", "processingMbps", "webrtcSessions", "timezone", "sync", "billing", "ingest", "live", "price" ], "additionalProperties": false } }, "required": [ "id", "name", "service", "engine", "engineLabel", "version", "versionLabel", "engineVersion", "status", "statusReason", "size", "storageUsedBytes", "storageTotalBytes", "publicAccess", "allowlistCount", "deletionProtection", "pendingRestart", "price", "activeOperation", "createdAt" ], "additionalProperties": false }, "operationId": { "type": "string" }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "initialApp": { "type": "object", "properties": { "appId": { "type": "string" }, "name": { "type": "string" }, "keyId": { "type": "string" }, "key": { "type": "string" } }, "required": [ "appId", "name", "keyId", "key" ], "additionalProperties": false, "nullable": true }, "stream": { "type": "object", "properties": { "host": { "type": "string" }, "firstInput": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "keys": { "type": "object", "properties": { "primary": { "type": "string" } }, "required": [ "primary" ], "additionalProperties": false } }, "required": [ "id", "name", "keys" ], "additionalProperties": false } }, "required": [ "host" ], "additionalProperties": false } }, "required": [ "instance", "operationId", "price", "initialApp" ], "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": { "instance": { "id": "string", "name": "string", "service": "database", "engine": "realtime", "engineLabel": "string", "version": "string", "versionLabel": "string", "engineVersion": "string", "status": "failed", "statusReason": "string", "size": { "cpu": 0, "memoryMib": 0, "storageGib": 0 }, "storageUsedBytes": 0, "storageTotalBytes": 0, "publicAccess": true, "allowlistCount": 0, "deletionProtection": true, "pendingRestart": true, "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "activeOperation": { "id": "string", "kind": "create", "status": "failed", "stepIndex": 0, "stepCount": 0, "stepLabel": "string" }, "createdAt": "string", "stream": { "host": "string", "speedMbps": 0, "processingMbps": 0, "webrtcSessions": 0, "timezone": "string", "sync": { "generation": 0, "appliedGeneration": 0, "lastSyncedAt": "string", "lastError": "string" }, "billing": { "allowed": true, "reason": "suspended" }, "ingest": { "rtmp": "string", "rtmps": "string", "srt": "string", "whipBase": "string", "icecastBase": "string" }, "live": { "inputsLive": 0, "channelsLive": 0, "viewers": 0, "egressMbps": 0, "at": "string" }, "price": { "speedMicroUsdPerHour": 0, "speedUsdPerMonth": 0 } } }, "operationId": "string", "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "initialApp": { "appId": "string", "name": "string", "keyId": "string", "key": "string" }, "stream": { "host": "string", "firstInput": { "id": "string", "name": "string", "keys": { "primary": "string" } } } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList managed instancesDetails +/api/v1/projects/:projectId/managed/instances
Lists the project's live instances, oldest first, with engine and version, status, size, public access, allowlist size, price and any operation in progress. Instances of services you cannot read are left out.
- Requires
database:readorrealtime:read. - Works only on a project of type
managed; other projects return409 MANAGED_PROJECT_REQUIRED.
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": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "service": { "type": "string", "enum": [ "database", "realtime", "stream" ] }, "engine": { "type": "string", "enum": [ "realtime", "postgresql", "mysql", "libsql", "stream" ] }, "engineLabel": { "type": "string" }, "version": { "type": "string" }, "versionLabel": { "type": "string" }, "engineVersion": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "failed", "deleted", "provisioning", "stopped", "running", "deleting", "starting", "stopping", "restarting", "updating" ] }, "statusReason": { "type": "string", "nullable": true }, "size": { "type": "object", "properties": { "cpu": { "type": "number" }, "memoryMib": { "type": "number" }, "storageGib": { "type": "number" } }, "required": [ "cpu", "memoryMib", "storageGib" ], "additionalProperties": false }, "storageUsedBytes": { "type": "number", "nullable": true }, "storageTotalBytes": { "type": "number", "nullable": true }, "publicAccess": { "type": "boolean" }, "allowlistCount": { "type": "number" }, "deletionProtection": { "type": "boolean" }, "pendingRestart": { "type": "boolean" }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "activeOperation": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "stepIndex": { "type": "number" }, "stepCount": { "type": "number" }, "stepLabel": { "type": "string", "nullable": true } }, "required": [ "id", "kind", "status", "stepIndex", "stepCount", "stepLabel" ], "additionalProperties": false, "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "stream": { "type": "object", "properties": { "host": { "type": "string" }, "speedMbps": { "type": "number" }, "processingMbps": { "type": "number" }, "webrtcSessions": { "type": "number" }, "timezone": { "type": "string" }, "sync": { "type": "object", "properties": { "generation": { "type": "number" }, "appliedGeneration": { "type": "number" }, "lastSyncedAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true } }, "required": [ "generation", "appliedGeneration", "lastSyncedAt", "lastError" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "allowed", "reason" ], "additionalProperties": false }, "ingest": { "type": "object", "properties": { "rtmp": { "type": "string" }, "rtmps": { "type": "string" }, "srt": { "type": "string" }, "whipBase": { "type": "string" }, "icecastBase": { "type": "string" } }, "required": [ "rtmp", "rtmps", "srt", "whipBase", "icecastBase" ], "additionalProperties": false }, "live": { "type": "object", "properties": { "inputsLive": { "type": "number" }, "channelsLive": { "type": "number" }, "viewers": { "type": "number" }, "egressMbps": { "type": "number" }, "at": { "type": "string" } }, "required": [ "inputsLive", "channelsLive", "viewers", "egressMbps", "at" ], "additionalProperties": false, "nullable": true }, "price": { "type": "object", "properties": { "speedMicroUsdPerHour": { "type": "number" }, "speedUsdPerMonth": { "type": "number" } }, "required": [ "speedMicroUsdPerHour", "speedUsdPerMonth" ], "additionalProperties": false } }, "required": [ "host", "speedMbps", "processingMbps", "webrtcSessions", "timezone", "sync", "billing", "ingest", "live", "price" ], "additionalProperties": false } }, "required": [ "id", "name", "service", "engine", "engineLabel", "version", "versionLabel", "engineVersion", "status", "statusReason", "size", "storageUsedBytes", "storageTotalBytes", "publicAccess", "allowlistCount", "deletionProtection", "pendingRestart", "price", "activeOperation", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "name": "string", "service": "database", "engine": "realtime", "engineLabel": "string", "version": "string", "versionLabel": "string", "engineVersion": "string", "status": "failed", "statusReason": "string", "size": { "cpu": 0, "memoryMib": 0, "storageGib": 0 }, "storageUsedBytes": 0, "storageTotalBytes": 0, "publicAccess": true, "allowlistCount": 0, "deletionProtection": true, "pendingRestart": true, "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "activeOperation": { "id": "string", "kind": "create", "status": "failed", "stepIndex": 0, "stepCount": 0, "stepLabel": "string" }, "createdAt": "string", "stream": { "host": "string", "speedMbps": 0, "processingMbps": 0, "webrtcSessions": 0, "timezone": "string", "sync": { "generation": 0, "appliedGeneration": 0, "lastSyncedAt": "string", "lastError": "string" }, "billing": { "allowed": true, "reason": "suspended" }, "ingest": { "rtmp": "string", "rtmps": "string", "srt": "string", "whipBase": "string", "icecastBase": "string" }, "live": { "inputsLive": 0, "channelsLive": 0, "viewers": 0, "egressMbps": 0, "at": "string" }, "price": { "speedMicroUsdPerHour": 0, "speedUsdPerMonth": 0 } } } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a managed instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/delete
Deletes the instance and its data. A queued change or an unfinished create is canceled first.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). confirmNamemust equal the instance name exactly; otherwise400 MANAGED_CONFIRMATION_MISMATCH.- Fails with
409 MANAGED_DELETION_PROTECTEDwhile deletion protection is on. - Asynchronous: returns an
operationId; pollGET /api/v1/projects/:projectId/managed/instances/:instanceId/operations/:operationId, which still answers after the instance is gone.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
confirmName | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" } }, "required": [ "operationId" ], "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": { "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTSet deletion protectionDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/deletion-protection/update
Turns deletion protection on or off. While it is on, delete requests for the instance are refused.
- Requires
database:admin(databases) orrealtime:admin(realtime servers).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
enabled | boolean | Yes |
Complete request schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deletionProtection": { "type": "boolean" } }, "required": [ "deletionProtection" ], "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": { "deletionProtection": true }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead a managed instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId
Returns the instance's full details: engine and version, status, size, storage use, price, endpoint, admin username and default database, TLS certificate fingerprint, available update and any operation in progress. Realtime servers also include their endpoint, app count and size profile.
- Requires
database:read(databases) orrealtime:read(realtime servers). - A missing or deleted instance returns
404 MANAGED_INSTANCE_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "service": { "type": "string", "enum": [ "database", "realtime", "stream" ] }, "engine": { "type": "string", "enum": [ "realtime", "postgresql", "mysql", "libsql", "stream" ] }, "engineLabel": { "type": "string" }, "version": { "type": "string" }, "versionLabel": { "type": "string" }, "engineVersion": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "failed", "deleted", "provisioning", "stopped", "running", "deleting", "starting", "stopping", "restarting", "updating" ] }, "statusReason": { "type": "string", "nullable": true }, "size": { "type": "object", "properties": { "cpu": { "type": "number" }, "memoryMib": { "type": "number" }, "storageGib": { "type": "number" } }, "required": [ "cpu", "memoryMib", "storageGib" ], "additionalProperties": false }, "storageUsedBytes": { "type": "number", "nullable": true }, "storageTotalBytes": { "type": "number", "nullable": true }, "publicAccess": { "type": "boolean" }, "allowlistCount": { "type": "number" }, "deletionProtection": { "type": "boolean" }, "pendingRestart": { "type": "boolean" }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "activeOperation": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "stepIndex": { "type": "number" }, "stepCount": { "type": "number" }, "stepLabel": { "type": "string", "nullable": true } }, "required": [ "id", "kind", "status", "stepIndex", "stepCount", "stepLabel" ], "additionalProperties": false, "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "stream": { "type": "object", "properties": { "host": { "type": "string" }, "speedMbps": { "type": "number" }, "processingMbps": { "type": "number" }, "webrtcSessions": { "type": "number" }, "timezone": { "type": "string" }, "sync": { "type": "object", "properties": { "generation": { "type": "number" }, "appliedGeneration": { "type": "number" }, "lastSyncedAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true } }, "required": [ "generation", "appliedGeneration", "lastSyncedAt", "lastError" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "allowed", "reason" ], "additionalProperties": false }, "ingest": { "type": "object", "properties": { "rtmp": { "type": "string" }, "rtmps": { "type": "string" }, "srt": { "type": "string" }, "whipBase": { "type": "string" }, "icecastBase": { "type": "string" } }, "required": [ "rtmp", "rtmps", "srt", "whipBase", "icecastBase" ], "additionalProperties": false }, "live": { "type": "object", "properties": { "inputsLive": { "type": "number" }, "channelsLive": { "type": "number" }, "viewers": { "type": "number" }, "egressMbps": { "type": "number" }, "at": { "type": "string" } }, "required": [ "inputsLive", "channelsLive", "viewers", "egressMbps", "at" ], "additionalProperties": false, "nullable": true }, "price": { "type": "object", "properties": { "speedMicroUsdPerHour": { "type": "number" }, "speedUsdPerMonth": { "type": "number" } }, "required": [ "speedMicroUsdPerHour", "speedUsdPerMonth" ], "additionalProperties": false } }, "required": [ "host", "speedMbps", "processingMbps", "webrtcSessions", "timezone", "sync", "billing", "ingest", "live", "price" ], "additionalProperties": false }, "endpoint": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "number", "nullable": true } }, "required": [ "host", "port" ], "additionalProperties": false, "nullable": true }, "adminUsername": { "type": "string", "nullable": true }, "defaultDatabase": { "type": "string", "nullable": true }, "capabilities": { "type": "object", "properties": { "databases": { "type": "boolean" }, "users": { "type": "boolean" }, "tokens": { "type": "boolean" }, "query": { "type": "boolean" }, "schema": { "type": "boolean" }, "explorer": { "type": "boolean" }, "config": { "type": "boolean" }, "rawConfig": { "type": "boolean" }, "certificate": { "type": "boolean" }, "extensions": { "type": "boolean" }, "insights": { "type": "boolean" }, "sessions": { "type": "boolean" }, "shell": { "type": "boolean" }, "export": { "type": "boolean" }, "import": { "type": "boolean" } }, "required": [ "databases", "users", "tokens", "query", "schema", "explorer", "config", "rawConfig", "certificate", "extensions", "insights", "sessions", "shell", "export", "import" ], "additionalProperties": false }, "backups": { "const": "coming_soon", "type": "string" }, "updateAvailable": { "type": "object", "properties": { "versionLabel": { "type": "string" } }, "required": [ "versionLabel" ], "additionalProperties": false, "nullable": true }, "tls": { "type": "object", "properties": { "fingerprintSha256": { "type": "string" }, "expiresAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "fingerprintSha256", "expiresAt" ], "additionalProperties": false, "nullable": true }, "credentialsRotatedAt": { "type": "string", "description": "Date string", "nullable": true }, "lastObservedAt": { "type": "string", "description": "Date string", "nullable": true }, "updatedAt": { "type": "string", "description": "Date string" }, "realtime": { "type": "object", "properties": { "host": { "type": "string" }, "wsUrl": { "type": "string" }, "httpUrl": { "type": "string" }, "apps": { "type": "number" }, "profile": { "type": "object", "properties": { "memoryMib": { "type": "number" }, "cpu": { "type": "number" }, "maxConnections": { "type": "number" }, "deliveriesPerSecond": { "type": "number" }, "publishesPerSecond": { "type": "number" }, "maxPayloadBytes": { "type": "number" }, "bandwidthMbps": { "type": "number" }, "historyMaxTtlSeconds": { "type": "number" }, "memoryLimitBytes": { "type": "number" } }, "required": [ "memoryMib", "cpu", "maxConnections", "deliveriesPerSecond", "publishesPerSecond", "maxPayloadBytes", "bandwidthMbps", "historyMaxTtlSeconds", "memoryLimitBytes" ], "additionalProperties": false }, "proxyLimits": { "type": "object", "properties": { "siteMaxConnections": { "type": "number" }, "perIpMaxConnections": { "type": "number" } }, "required": [ "siteMaxConnections", "perIpMaxConnections" ], "additionalProperties": false }, "sync": { "type": "object", "properties": { "generation": { "type": "number" }, "appliedGeneration": { "type": "number" }, "inSync": { "type": "boolean" }, "lastSyncedAt": { "type": "string", "description": "Date string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "lastErrorAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "generation", "appliedGeneration", "inSync", "lastSyncedAt", "lastError", "lastErrorAt" ], "additionalProperties": false } }, "required": [ "host", "wsUrl", "httpUrl", "apps", "profile", "proxyLimits", "sync" ], "additionalProperties": false, "nullable": true } }, "required": [ "id", "name", "service", "engine", "engineLabel", "version", "versionLabel", "engineVersion", "status", "statusReason", "size", "storageUsedBytes", "storageTotalBytes", "publicAccess", "allowlistCount", "deletionProtection", "pendingRestart", "price", "activeOperation", "createdAt", "endpoint", "adminUsername", "defaultDatabase", "capabilities", "backups", "updateAvailable", "tls", "credentialsRotatedAt", "lastObservedAt", "updatedAt", "realtime" ], "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", "service": "database", "engine": "realtime", "engineLabel": "string", "version": "string", "versionLabel": "string", "engineVersion": "string", "status": "failed", "statusReason": "string", "size": { "cpu": 0, "memoryMib": 0, "storageGib": 0 }, "storageUsedBytes": 0, "storageTotalBytes": 0, "publicAccess": true, "allowlistCount": 0, "deletionProtection": true, "pendingRestart": true, "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "activeOperation": { "id": "string", "kind": "create", "status": "failed", "stepIndex": 0, "stepCount": 0, "stepLabel": "string" }, "createdAt": "string", "stream": { "host": "string", "speedMbps": 0, "processingMbps": 0, "webrtcSessions": 0, "timezone": "string", "sync": { "generation": 0, "appliedGeneration": 0, "lastSyncedAt": "string", "lastError": "string" }, "billing": { "allowed": true, "reason": "suspended" }, "ingest": { "rtmp": "string", "rtmps": "string", "srt": "string", "whipBase": "string", "icecastBase": "string" }, "live": { "inputsLive": 0, "channelsLive": 0, "viewers": 0, "egressMbps": 0, "at": "string" }, "price": { "speedMicroUsdPerHour": 0, "speedUsdPerMonth": 0 } }, "endpoint": { "host": "string", "port": 0 }, "adminUsername": "string", "defaultDatabase": "string", "capabilities": { "databases": true, "users": true, "tokens": true, "query": true, "schema": true, "explorer": true, "config": true, "rawConfig": true, "certificate": true, "extensions": true, "insights": true, "sessions": true, "shell": true, "export": true, "import": true }, "backups": "string", "updateAvailable": { "versionLabel": "string" }, "tls": { "fingerprintSha256": "string", "expiresAt": "string" }, "credentialsRotatedAt": "string", "lastObservedAt": "string", "updatedAt": "string", "realtime": { "host": "string", "wsUrl": "string", "httpUrl": "string", "apps": 0, "profile": { "memoryMib": 0, "cpu": 0, "maxConnections": 0, "deliveriesPerSecond": 0, "publishesPerSecond": 0, "maxPayloadBytes": 0, "bandwidthMbps": 0, "historyMaxTtlSeconds": 0, "memoryLimitBytes": 0 }, "proxyLimits": { "siteMaxConnections": 0, "perIpMaxConnections": 0 }, "sync": { "generation": 0, "appliedGeneration": 0, "inSync": true, "lastSyncedAt": "string", "lastError": "string", "lastErrorAt": "string" } } }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTReplace the IP allowlistDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/network/allowlist/update
Replaces the instance's IP allowlist with the given CIDR ranges. An empty list opens the instance to every address. On a realtime server the allowlist restricts only the server API; WebSocket clients are never IP-restricted.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). revisionmust equal the current allowlist revision from the network endpoint; otherwise409 MANAGED_ALLOWLIST_CONFLICT.- Up to 64 entries; labels are cut to 64 characters. Invalid or duplicate ranges return
400 MANAGED_INVALID_ALLOWLIST. - Asynchronous: returns an
operationIdand the newrevision; poll the instance operation until it ends. The instance must be running or stopped (409 MANAGED_INVALID_STATE).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
entries | object[] | Yes |
revision | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cidr": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"cidr"
],
"additionalProperties": false
}
},
"revision": {
"type": "number"
}
},
"required": [
"entries",
"revision"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" }, "revision": { "type": "number" }, "entries": { "type": "number" } }, "required": [ "operationId", "revision", "entries" ], "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": { "operationId": "string", "revision": 0, "entries": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead network settingsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/network
Returns the instance's endpoint host and port, whether public access is on, the IP allowlist with its revision, whether allowlists are supported for this instance and what the allowlist restricts. TLS is always required.
- Requires
database:read(databases) orrealtime:read(realtime servers). - Pass
revisionback when replacing the allowlist.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "publicAccess": { "type": "boolean" }, "endpoint": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "number", "nullable": true } }, "required": [ "host", "port" ], "additionalProperties": false }, "allowlist": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "cidr", "label", "createdAt" ], "additionalProperties": false } }, "openToAll": { "type": "boolean" }, "revision": { "type": "number" }, "tlsRequired": { "const": true, "type": "boolean" }, "allowlistSupported": { "type": "boolean" }, "maxEntries": { "type": "number" }, "allowlistScope": { "type": "string", "enum": [ "connections", "server_api" ] }, "publicAccessEditable": { "type": "boolean" } }, "required": [ "publicAccess", "endpoint", "allowlist", "openToAll", "revision", "tlsRequired", "allowlistSupported", "maxEntries", "allowlistScope", "publicAccessEditable" ], "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": { "publicAccess": true, "endpoint": { "host": "string", "port": 0 }, "allowlist": [ { "cidr": "string", "label": "string", "createdAt": "string" } ], "openToAll": true, "revision": 0, "tlsRequired": true, "allowlistSupported": true, "maxEntries": 0, "allowlistScope": "connections", "publicAccessEditable": true }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList instance operationsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/operations
Lists the instance's operations, newest first, with kind, status, steps and any error.
- Requires
database:read(databases) orrealtime:read(realtime servers). limitdefaults to 50 and is capped at 200.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
limit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "instanceId": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "failed", "succeeded", "running", "skipped" ] }, "startedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true } }, "required": [ "key", "label", "status", "startedAt", "finishedAt" ], "additionalProperties": false } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false, "nullable": true }, "actorUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "finishedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "id", "instanceId", "kind", "status", "steps", "error", "actorUserId", "createdAt", "finishedAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "instanceId": "string", "kind": "create", "status": "failed", "steps": [ { "key": "string", "label": "string", "status": "pending", "startedAt": "string", "finishedAt": "string" } ], "error": { "code": "string", "message": "string" }, "actorUserId": "string", "createdAt": "string", "finishedAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead an operationDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/operations/:operationId
Returns one operation with its kind, status (queued, running, succeeded, failed or canceled), each step's progress and, when it failed, the error code and message. Use it to poll asynchronous changes.
- Requires
database:read(databases) orrealtime:read(realtime servers). - Also answers for a deleted instance, so a delete can be followed to the end.
- An unknown operation returns
404 MANAGED_OPERATION_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
operationId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "instanceId": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "failed", "succeeded", "running", "skipped" ] }, "startedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true } }, "required": [ "key", "label", "status", "startedAt", "finishedAt" ], "additionalProperties": false } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false, "nullable": true }, "actorUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "finishedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "id", "instanceId", "kind", "status", "steps", "error", "actorUserId", "createdAt", "finishedAt" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "instanceId": "string", "kind": "create", "status": "failed", "steps": [ { "key": "string", "label": "string", "status": "pending", "startedAt": "string", "finishedAt": "string" } ], "error": { "code": "string", "message": "string" }, "actorUserId": "string", "createdAt": "string", "finishedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTResize an instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/resize
Changes the instance's CPU, memory or storage; omitted fields keep their current value. Storage can grow but never shrink. Database CPU or memory changes take effect after a restart unless restart is true; realtime servers apply the new size live.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). quotedHourlyTotalmust match the new size's current price, or the call fails with409 MANAGED_PRICE_CHANGED.- Asynchronous: returns an
operationId, the newpriceandrestartRecommended; poll the instance operation until it ends. - Errors:
409 MANAGED_INVALID_STATE(instance not running),400 MANAGED_STORAGE_SHRINK_UNSUPPORTED,400 MANAGED_RESIZE_NOOP,400 MANAGED_INVALID_SIZE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
cpu | number | No |
memoryMib | number | No |
storageGib | number | No |
restart | boolean | No |
speedMbps | number | No |
processingMbps | number | No |
quotedHourlyTotal | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"cpu": {
"type": "number"
},
"memoryMib": {
"type": "number"
},
"storageGib": {
"type": "number"
},
"restart": {
"type": "boolean"
},
"speedMbps": {
"type": "number"
},
"processingMbps": {
"type": "number"
},
"quotedHourlyTotal": {
"type": "number"
}
},
"required": [
"quotedHourlyTotal"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "restartRecommended": { "type": "boolean" } }, "required": [ "operationId", "price", "restartRecommended" ], "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": { "operationId": "string", "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "restartRecommended": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRestart an instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/restart
Restarts a running or failed instance.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). - Asynchronous: returns an
operationId; poll the instance operation until it ends. - Errors:
409 MANAGED_INVALID_STATE,409 MANAGED_OPERATION_IN_PROGRESS,402 INSUFFICIENT_BALANCE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" } }, "required": [ "operationId" ], "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": { "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTStart an instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/start
Starts a stopped or failed instance. Compute and management charges resume while it runs.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). - Asynchronous: returns an
operationId; poll the instance operation until it ends. - Errors:
409 MANAGED_INVALID_STATE,409 MANAGED_OPERATION_IN_PROGRESS,402 INSUFFICIENT_BALANCE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" } }, "required": [ "operationId" ], "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": { "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTStop an instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stop
Stops a running or failed instance. Its data is kept and a stopped instance is charged for storage only.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). - Asynchronous: returns an
operationId; poll the instance operation until it ends. - Errors:
409 MANAGED_INVALID_STATE,409 MANAGED_OPERATION_IN_PROGRESS.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" } }, "required": [ "operationId" ], "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": { "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTRename an instanceDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/update
Changes the instance's display name and returns the updated instance summary.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). - Names use 3-48 lowercase letters, numbers and hyphens, start with a letter and have no consecutive hyphens (
400 MANAGED_INVALID_NAME). - A name already used in the project returns
409 MANAGED_NAME_TAKEN.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"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" }, "service": { "type": "string", "enum": [ "database", "realtime", "stream" ] }, "engine": { "type": "string", "enum": [ "realtime", "postgresql", "mysql", "libsql", "stream" ] }, "engineLabel": { "type": "string" }, "version": { "type": "string" }, "versionLabel": { "type": "string" }, "engineVersion": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "failed", "deleted", "provisioning", "stopped", "running", "deleting", "starting", "stopping", "restarting", "updating" ] }, "statusReason": { "type": "string", "nullable": true }, "size": { "type": "object", "properties": { "cpu": { "type": "number" }, "memoryMib": { "type": "number" }, "storageGib": { "type": "number" } }, "required": [ "cpu", "memoryMib", "storageGib" ], "additionalProperties": false }, "storageUsedBytes": { "type": "number", "nullable": true }, "storageTotalBytes": { "type": "number", "nullable": true }, "publicAccess": { "type": "boolean" }, "allowlistCount": { "type": "number" }, "deletionProtection": { "type": "boolean" }, "pendingRestart": { "type": "boolean" }, "price": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "type": "number" }, "hourly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false }, "monthly": { "type": "object", "properties": { "compute": { "type": "number" }, "storage": { "type": "number" }, "management": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compute", "storage", "management", "total" ], "additionalProperties": false } }, "required": [ "currency", "hoursPerMonth", "hourly", "monthly" ], "additionalProperties": false }, "activeOperation": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "stepIndex": { "type": "number" }, "stepCount": { "type": "number" }, "stepLabel": { "type": "string", "nullable": true } }, "required": [ "id", "kind", "status", "stepIndex", "stepCount", "stepLabel" ], "additionalProperties": false, "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "stream": { "type": "object", "properties": { "host": { "type": "string" }, "speedMbps": { "type": "number" }, "processingMbps": { "type": "number" }, "webrtcSessions": { "type": "number" }, "timezone": { "type": "string" }, "sync": { "type": "object", "properties": { "generation": { "type": "number" }, "appliedGeneration": { "type": "number" }, "lastSyncedAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true } }, "required": [ "generation", "appliedGeneration", "lastSyncedAt", "lastError" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "allowed", "reason" ], "additionalProperties": false }, "ingest": { "type": "object", "properties": { "rtmp": { "type": "string" }, "rtmps": { "type": "string" }, "srt": { "type": "string" }, "whipBase": { "type": "string" }, "icecastBase": { "type": "string" } }, "required": [ "rtmp", "rtmps", "srt", "whipBase", "icecastBase" ], "additionalProperties": false }, "live": { "type": "object", "properties": { "inputsLive": { "type": "number" }, "channelsLive": { "type": "number" }, "viewers": { "type": "number" }, "egressMbps": { "type": "number" }, "at": { "type": "string" } }, "required": [ "inputsLive", "channelsLive", "viewers", "egressMbps", "at" ], "additionalProperties": false, "nullable": true }, "price": { "type": "object", "properties": { "speedMicroUsdPerHour": { "type": "number" }, "speedUsdPerMonth": { "type": "number" } }, "required": [ "speedMicroUsdPerHour", "speedUsdPerMonth" ], "additionalProperties": false } }, "required": [ "host", "speedMbps", "processingMbps", "webrtcSessions", "timezone", "sync", "billing", "ingest", "live", "price" ], "additionalProperties": false } }, "required": [ "id", "name", "service", "engine", "engineLabel", "version", "versionLabel", "engineVersion", "status", "statusReason", "size", "storageUsedBytes", "storageTotalBytes", "publicAccess", "allowlistCount", "deletionProtection", "pendingRestart", "price", "activeOperation", "createdAt" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "name": "string", "service": "database", "engine": "realtime", "engineLabel": "string", "version": "string", "versionLabel": "string", "engineVersion": "string", "status": "failed", "statusReason": "string", "size": { "cpu": 0, "memoryMib": 0, "storageGib": 0 }, "storageUsedBytes": 0, "storageTotalBytes": 0, "publicAccess": true, "allowlistCount": 0, "deletionProtection": true, "pendingRestart": true, "price": { "currency": "string", "hoursPerMonth": 0, "hourly": { "compute": 0, "storage": 0, "management": 0, "total": 0 }, "monthly": { "compute": 0, "storage": 0, "management": 0, "total": 0 } }, "activeOperation": { "id": "string", "kind": "create", "status": "failed", "stepIndex": 0, "stepCount": 0, "stepLabel": "string" }, "createdAt": "string", "stream": { "host": "string", "speedMbps": 0, "processingMbps": 0, "webrtcSessions": 0, "timezone": "string", "sync": { "generation": 0, "appliedGeneration": 0, "lastSyncedAt": "string", "lastError": "string" }, "billing": { "allowed": true, "reason": "suspended" }, "ingest": { "rtmp": "string", "rtmps": "string", "srt": "string", "whipBase": "string", "icecastBase": "string" }, "live": { "inputsLive": 0, "channelsLive": 0, "viewers": 0, "egressMbps": 0, "at": "string" }, "price": { "speedMicroUsdPerHour": 0, "speedUsdPerMonth": 0 } } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTApply an available updateDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/upgrade
Moves a running instance to the latest build of its current engine version. The instance detail shows updateAvailable when one exists.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). - Asynchronous: returns an
operationId; poll the instance operation until it ends. - Errors:
409 MANAGED_UP_TO_DATE,409 MANAGED_INVALID_STATE(instance not running).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" } }, "required": [ "operationId" ], "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": { "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList project operationsDetails +/api/v1/projects/:projectId/managed/operations
Lists operations across all instances in the project, newest first, with kind, status, steps and any error. Operations on services you cannot read are left out.
- Requires
database:readorrealtime:read. limitdefaults to 50 and is capped at 200.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
limit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "instanceId": { "type": "string" }, "kind": { "type": "string", "enum": [ "create", "restart", "delete", "start", "resize", "stop", "config_apply", "network_update", "upgrade", "export", "import" ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "canceled", "queued", "running" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "failed", "succeeded", "running", "skipped" ] }, "startedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "string", "nullable": true } }, "required": [ "key", "label", "status", "startedAt", "finishedAt" ], "additionalProperties": false } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false, "nullable": true }, "actorUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "finishedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "id", "instanceId", "kind", "status", "steps", "error", "actorUserId", "createdAt", "finishedAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "instanceId": "string", "kind": "create", "status": "failed", "steps": [ { "key": "string", "label": "string", "status": "pending", "startedAt": "string", "finishedAt": "string" } ], "error": { "code": "string", "message": "string" }, "actorUserId": "string", "createdAt": "string", "finishedAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead connection detailsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/connection
Return the server's host, wsUrl and httpUrl, readiness, each app's ID and newest public key, ready-made pusher-js options, and the variable names each binding preset writes. Contains no secrets.
- Requires
realtime:read. - Clients connect by host on port 443;
clusteris a placeholder (mt1). serverApiAllowlistis true when the IP allowlist restricts the server REST API.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "host": { "type": "string" }, "wsUrl": { "type": "string" }, "httpUrl": { "type": "string" }, "port": { "const": 443, "type": "number" }, "ready": { "type": "boolean" }, "serverApiAllowlist": { "type": "boolean" }, "apps": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "key": { "type": "string", "nullable": true }, "encryption": { "type": "string", "enum": [ "off", "optional", "required" ] } }, "required": [ "appId", "name", "enabled", "key", "encryption" ], "additionalProperties": false } }, "pusher": { "type": "object", "properties": { "wsHost": { "type": "string" }, "wsPort": { "const": 443, "type": "number" }, "wssPort": { "const": 443, "type": "number" }, "forceTLS": { "const": true, "type": "boolean" }, "enabledTransports": { "type": "array", "items": { "type": "string", "enum": [ "ws", "wss" ] } }, "cluster": { "const": "mt1", "type": "string" }, "disableStats": { "const": true, "type": "boolean" } }, "required": [ "wsHost", "wsPort", "wssPort", "forceTLS", "enabledTransports", "cluster", "disableStats" ], "additionalProperties": false }, "env": { "type": "object", "properties": { "hubfly": { "type": "array", "items": { "type": "string" } }, "laravel": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "array", "items": { "type": "string" } }, "e2eKeys": { "type": "string" } }, "required": [ "hubfly", "laravel", "secret", "e2eKeys" ], "additionalProperties": false } }, "required": [ "host", "wsUrl", "httpUrl", "port", "ready", "serverApiAllowlist", "apps", "pusher", "env" ], "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": { "host": "string", "wsUrl": "string", "httpUrl": "string", "port": 0, "ready": true, "serverApiAllowlist": true, "apps": [ { "appId": "string", "name": "string", "enabled": true, "key": "string", "encryption": "off" } ], "pusher": { "wsHost": "string", "wsPort": 0, "wssPort": 0, "forceTLS": true, "enabledTransports": [ "ws" ], "cluster": "string", "disableStats": true }, "env": { "hubfly": [ "string" ], "laravel": [ "string" ], "secret": [ "string" ], "e2eKeys": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
Related guides
- Realtime overview and workflows
- Realtime protocol reference (WebSocket, server API and webhooks)
- All Realtime API sections
- Dashboard errors and status codes