Managed Databases API · Dashboard
Instances & lifecycle
Create a database instance, then start, stop, restart, resize, upgrade, rename, protect or delete it and follow its 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.
Database instances live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the database instance ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the database permissions must hold that exact permission.
How to use these endpoints
- Get the current hourly quote for the size, then create the instance with
quotedHourlyTotaland a uniqueidempotencyKey. A changed price returns409 MANAGED_PRICE_CHANGED; fetch a new quote and retry. - Create, power, resize and upgrade calls are asynchronous. Poll the returned operation until it ends before sending the next change.
- Storage can only grow. CPU and memory change without a restart; if the engine needs one to apply its settings,
restart: truerestarts during the resize, otherwise the instance reports a pending restart. - Deletion needs the instance name in
confirmNameand fails while deletion protection is on.
Create a PostgreSQL instance
# 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=10" \
-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":"app-db","service":"database","engine":"postgresql","size":{"cpu":0.25,"memoryMib":512,"storageGib":10},"quotedHourlyTotal":'"$QUOTE"',"idempotencyKey":"create-app-db-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 (14)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
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" } }
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" } }