Deployments

Upgrade deployment

Upgrade a managed Core instance through Blnk Cloud.

POST/deployments/{deployment_id}/upgrade

Use this endpoint to upgrade a managed Core to the latest version Cloud supports. The deployment must be ACTIVE. See Managed instances to learn more.

Cloud starts a new runtime next to the current one, health-checks it, then cuts traffic over. Ledger data and the Core secret stay in place.

Cloud creates a new deployment_id and a new instance_id. After cutover, use those new ids. Any requests sent to the old instance_id would fail or return errors.

The response returns the new deployment_id on new_deployment. Get the new instance_id from Get deployment details once the successor is provisioned.

Enterprise authentication

Send these requests to https://api.cloud.blnkfinance.com on Blnk Cloud. On a self-hosted Enterprise deployment, send them to ENTERPRISE_PUBLIC_URL.

Pass an Enterprise API key, or an OAuth access token, in the X-blnk-key header. Create the key in Enterprise API keys, or issue a token with Enterprise OAuth.

This credential comes from the Cloud or Enterprise workspace. A Core API key belongs to the Core instance.

X-blnk-keystringrequiredheader

Enterprise API key, or an OAuth access token.

Path

deployment_idstringrequiredpath

Unique id of the deployment to upgrade (deploy_...). Do not pass instance_id here.

Body

The body is optional. Omit it, or send {}, to upgrade to the latest Core version Cloud supports.

forcebooleanbody

Set to true to run the upgrade even when the deployment is already on the latest version. Default is false. When false and the deployment is already current, Cloud returns upgrade_status: "skipped".

Response

new_deploymentobject

The successor deployment Cloud is bringing up. Same shape as Get deployment details. Use this deployment_id for later Deployments API calls.

old_deployment_idstring

The deployment_id you passed in the path. Cloud marks it UPGRADING, then retires it after cutover.

previous_versionstring

Core version the old deployment was running.

new_versionstring

Core version Cloud is rolling out.

upgrade_statusstring

in_progress when Cloud accepted the upgrade. skipped when the deployment is already on the latest version and you did not send force: true.

messagestring

Human-readable status. Track progress with Get deployment details on new_deployment.deployment_id.

curl -X POST 'https://api.cloud.blnkfinance.com/deployments/deploy_073f7ffe-9dfd-42ce-aa50-d1dca1788adc/upgrade' \
  -H 'X-blnk-key: CLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "new_deployment": {
    "deployment_id": "deploy_a1c83e2f-4b19-4d6a-9e2c-7f1b0c8d4e55",
    "name": "my-sandbox",
    "ingress_mode": "shared",
    "dedicated": false,
    "tier": "B1.Micro",
    "type": "sandbox",
    "region": "nyc3",
    "status": "PENDING",
    "watch_enabled": false,
    "usage_billing_enabled": true,
    "usage_billing_enabled_at": "2026-09-09T07:20:08.028229Z",
    "record_creates_blocked": false,
    "created_at": "2026-09-16T08:12:04.551203Z",
    "updated_at": "2026-09-16T08:12:04.551203Z"
  },
  "old_deployment_id": "deploy_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
  "previous_version": "0.15.0",
  "new_version": "0.15.4",
  "upgrade_status": "in_progress",
  "message": "Upgrade initiated. The new deployment will take over once health checks pass."
}

{
  "upgrade_status": "skipped",
  "message": "Deployment is already running the latest version. Use force=true to upgrade anyway."
}