Update a deployment

PUT

/api/v1/deployments/{id}

curl --request PUT \
  --url http://localhost:3000/api/v1/deployments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "name": "example", "deviceSelector": { "matchLabels": { "additionalProperty": "example" }, "matchExpressions": [ { "key": "example", "operator": "In", "values": [ "example" ] } ] }, "parameterOverrides": {}, "targetNamespace": "example", "desiredState": "PENDING", "priority": 1, "scheduledAt": "2026-04-15T12:00:00Z", "metadata": {} }'

• Development
• Production

Updates an existing deployment.

Authorizations

• api-key
• bearer

Parameters

Path Parameters

id

required

string format: uuid

Deployment UUID

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Body^required

Media typeapplication/json

object

name

Name of the deployment

string

deviceSelector

Devices to target by device id or labels

object

matchLabels

Labels a device must carry (all must match)

object

key

additional properties

string

matchExpressions

Label expressions a device must satisfy (all must match)

Array<object>

<= 100 items

object

key

required

Label key

string

operator

required

Match operator

string

Allowed values: In NotIn Exists DoesNotExist

values

Label values (for In and NotIn)

Array<string>

<= 10000 items

parameterOverrides

Parameter values that override the application defaults

object

key

additional properties

any

targetNamespace

Kubernetes namespace for the workload (DNS-1123 label). null clears the override and returns to the organization slug. Omitted leaves it unchanged.

string

nullable /^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$/

desiredState

Desired state of the deployment

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

priority

Priority

number

<= 100

scheduledAt

When the deployment is scheduled to start (ISO 8601)

string format: date-time

metadata

Free-form metadata

object

key

additional properties

any

Responses

200

Deployment updated successfully

Media typeapplication/json

object

id

required

string format: uuid

organizationId

required

string format: uuid

name

required

string

applicationDescriptionId

required

string format: uuid

deviceSelector

required

object

matchLabels

Labels a device must carry (all must match)

object

key

additional properties

string

matchExpressions

Label expressions a device must satisfy (all must match)

Array<object>

<= 100 items

object

key

required

Label key

string

operator

required

Match operator

string

Allowed values: In NotIn Exists DoesNotExist

values

Label values (for In and NotIn)

Array<string>

<= 10000 items

parameterOverrides

required

Application parameter overrides

object

key

additional properties

any

currentRevision

FM-1447: the revision number the deployment targets (1, then +1 per re-deploy). Set on the detail response only.

number

deploymentProfileId

FM-846: the manifest deploymentProfiles[].id this deployment deploys; absent when the description declared nothing to choose between

string

deploymentProfile

FM-1362: the deployed profile summarised (type + component names); absent when no profile is recorded or it is not in the manifest any more

object

id

required

The manifest deploymentProfiles[].id

string

type

Rc2 wire type of the profile’s own type; absent for an off-spec type

string

Allowed values: helm compose

components

required

Array<object>

object

name

required

Component name

string

deploymentGroupId

FM-1159: the grouping key shared by every deployment created from the same multi-profile submission; absent for an ungrouped deployment

string format: uuid

deploymentGroup

FM-1159: every sibling row of this deployment group, including this one, in creation order. Absent when the deployment is ungrouped.

object

id

required

The deployment group id

string format: uuid

members

required

All members including the deployment this group is attached to, in creation order

Array<object>

object

id

required

string format: uuid

deploymentProfileId

The manifest deploymentProfiles[].id this member deploys

string

status

required

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

deploymentProfile

FM-1362: the member’s profile summarised (type + components), when resolvable

object

id

required

The manifest deploymentProfiles[].id

string

type

Rc2 wire type of the profile’s own type; absent for an off-spec type

string

Allowed values: helm compose

components

required

Array<object>

object

name

required

Component name

string

targetNamespace

FM-1258: the operator-chosen Margo metadata.namespace; absent when the organization slug (tenant default) is used

string

targetGroups

FM-1201: the device groups targeted at create time (name snapshots)

Array<object>

object

deviceGroupId

Device group UUID; absent when the group was deleted

string format: uuid

name

required

Name of the group when the deployment was created

string

deleted

required

True when the group no longer exists

boolean

currentName

The live group’s current name, when it differs from the snapshot

string

splitFromDeploymentId

FM-1412: the deployment this one was split from, if any

string format: uuid

deletionRequestedAt

FM-1484: when the deployment was deleted. Set while the removal is not finalised (status is REMOVING); the deployment is then read-only.

string format: date-time

desiredState

required

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

status

required

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

statusMessage

string

priority

required

Priority (0-100)

number

scheduledAt

string format: date-time

startedAt

string format: date-time

completedAt

string format: date-time

metadata

required

object

key

additional properties

any

rolloutStrategy

required

Rollout strategy type

string

Allowed values: IMMEDIATE CANARY ROLLING

rolloutPhase

required

Current rollout phase

string

Allowed values: PENDING CANARY_DEPLOYING CANARY_VALIDATING CANARY_PROMOTED ROLLING_IN_PROGRESS PAUSED COMPLETED ROLLED_BACK

rolloutConfig

required

Rollout configuration (strategy-specific)

object

key

additional properties

any

rollbackConfig

required

Rollback configuration (enabled, thresholdType, thresholdValue)

object

key

additional properties

any

currentBatch

required

Current batch number (for rolling/canary)

number

totalBatches

required

Total number of batches

number

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

lastStatusChangeAt

FM-1475: when the deployment last changed state (newest of creation, start, completion and any instance status-history entry). Set on list responses only.

string format: date-time

applicationDescription

object

id

required

string format: uuid

version

required

Application version string

string

applicationPackage

object

id

required

string format: uuid

name

required

string

instances

Array<object>

object

id

required

string format: uuid

deploymentId

required

string format: uuid

deviceId

required

string format: uuid

bundleDigest

Digest of the bundle served to the device

string

status

required

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

statusMessage

string

lastStatusReportAt

string format: date-time

downloadProgress

Download progress in percent

number

deployAttempts

required

Number of deploy attempts so far

number

lastDeployError

string

componentStatuses

required

FM-845: per-component states from the most recent status report. Empty until the device has reported.

Array<object>

object

name

required

Component name

string

state

required

Component state as reported by the device (rc2, lowercase)

string

error

object

code

Machine-readable error code

string

source

Component or subsystem that raised the error

string

message

Human-readable error message

string

statusError

FM-845: the structured status.error from the most recent report

object

code

Machine-readable error code

string

source

Component or subsystem that raised the error

string

message

Human-readable error message

string

batchNumber

Batch number for rolling updates (1-based)

number

isCanary

required

Whether this instance is part of the canary group

boolean

excludedAt

FM-1301: when the operator removed the deployment from this device alone. The device stays excluded until it is re-included.

string format: date-time

excludedBy

FM-1301: users.id of the operator who removed the deployment from this device

string

edgeDeploymentId

FM-1411: the Margo ApplicationDeployment.id the device knows this item by. Equals deploymentId unless the item was split off another deployment.

string format: uuid

viaDeviceGroupIds

FM-1202: the targeted device groups that contained the device at create time

Array<string>

directTarget

FM-1202: selected directly (device list or label selector)

boolean

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

device

object

id

required

string format: uuid

clientId

required

Margo clientId the device authenticates with

string

name

Device display name

string

status

required

Device status

string

statusHistory

Recent status history entries for this instance (up to 10, newest first)

Array<object>

object

id

required

string format: uuid

status

required

Status the instance moved to

string

message

string

reportedBy

Who or what reported the change

string

createdAt

required

string format: date-time

components

FM-845: per-component states reported at this point in time

Array<object>

object

name

required

Component name

string

state

required

Component state as reported by the device (rc2, lowercase)

string

error

object

code

Machine-readable error code

string

source

Component or subsystem that raised the error

string

message

Human-readable error message

string

error

FM-845: the structured top-level error reported at this point in time

object

code

Machine-readable error code

string

source

Component or subsystem that raised the error

string

message

Human-readable error message

string

instanceCount

Number of targeted instances

number

runningInstances

Number of instances in status INSTALLED

number

failedInstances

Number of instances in status FAILED

number

Example

{
  "deviceSelector": {
    "matchExpressions": [
      {
        "operator": "In"
      }
    ]
  },
  "deploymentProfile": {
    "type": "helm"
  },
  "deploymentGroup": {
    "members": [
      {
        "status": "PENDING",
        "deploymentProfile": {
          "type": "helm"
        }
      }
    ]
  },
  "desiredState": "PENDING",
  "status": "PENDING",
  "rolloutStrategy": "IMMEDIATE",
  "rolloutPhase": "PENDING",
  "instances": [
    {
      "status": "PENDING"
    }
  ]
}

400

Bad request - Invalid deployment data

401

Unauthorized - Invalid or missing authentication

403

Forbidden — caller lacks required permission

404

Deployment not found

409

Conflict - the deployment is being deleted and can no longer be changed