Create a deployment
const url = 'http://localhost:3000/api/v1/deployments';const options = { method: 'POST', headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'}, body: '{"name":"example","applicationDescriptionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","deviceSelector":{"matchLabels":{"additionalProperty":"example"},"matchExpressions":[{"key":"example","operator":"In","values":["example"]}]},"deviceGroupIds":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"parameterOverrides":{},"deploymentProfileId":"example","deploymentProfileIds":["example"],"targetNamespace":"example","desiredState":"PENDING","priority":1,"scheduledAt":"2026-04-15T12:00:00Z","metadata":{},"rolloutConfig":{"strategy":"IMMEDIATE","canaryPercentage":1,"canaryCount":1,"canarySuccessWindowMinutes":1,"autoPromote":true,"autoPromoteDelayMinutes":1,"batchSize":1,"wavePercentages":[1],"autoProgress":true,"autoProgressDelayMinutes":1},"rollbackConfig":{"enabled":true,"thresholdType":"NONE","thresholdValue":1},"skipScheduleCheck":true,"scheduleOverrideReason":"example","skipScopeLimitCheck":true,"scopeLimitOverrideReason":"example","skipTargetPermissionCheck":true,"targetPermissionOverrideReason":"example","userId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","groupIds":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/v1/deployments \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data '{ "name": "example", "applicationDescriptionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "deviceSelector": { "matchLabels": { "additionalProperty": "example" }, "matchExpressions": [ { "key": "example", "operator": "In", "values": [ "example" ] } ] }, "deviceGroupIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "parameterOverrides": {}, "deploymentProfileId": "example", "deploymentProfileIds": [ "example" ], "targetNamespace": "example", "desiredState": "PENDING", "priority": 1, "scheduledAt": "2026-04-15T12:00:00Z", "metadata": {}, "rolloutConfig": { "strategy": "IMMEDIATE", "canaryPercentage": 1, "canaryCount": 1, "canarySuccessWindowMinutes": 1, "autoPromote": true, "autoPromoteDelayMinutes": 1, "batchSize": 1, "wavePercentages": [ 1 ], "autoProgress": true, "autoProgressDelayMinutes": 1 }, "rollbackConfig": { "enabled": true, "thresholdType": "NONE", "thresholdValue": 1 }, "skipScheduleCheck": true, "scheduleOverrideReason": "example", "skipScopeLimitCheck": true, "scopeLimitOverrideReason": "example", "skipTargetPermissionCheck": true, "targetPermissionOverrideReason": "example", "userId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "groupIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }'Creates a new deployment.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”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 Bodyrequired
Section titled “Request Bodyrequired”object
Name of the deployment
ID of the application description to deploy
Devices to target by device id or labels. Optional when deviceGroupIds is given. At least one of the two is required. Resolved once, at create time.
object
Labels a device must carry (all must match)
object
Label expressions a device must satisfy (all must match)
object
Label key
Match operator
Label values (for In and NotIn)
Device groups to target. Their current members are resolved once, at create time, and merged with deviceSelector without duplicates. Devices added to a group later do not receive this deployment. Every id must be a live group of the organization.
Parameter values that override the application defaults
object
ID of the deployment profile to deploy. Required when the application description declares more than one servable profile. Deprecated: use deploymentProfileIds. Sending both is refused.
IDs of the deployment profiles to deploy. Each id creates one deployment, and all of them share one deployment group id. Every id must be declared by the application description. Sending deploymentProfileId as well is refused.
Kubernetes namespace for the workload (DNS-1123 label). Defaults to the organization slug.
Desired state of the deployment
Priority
When the deployment is scheduled to start (ISO 8601)
Free-form metadata
object
Rollout configuration. Defaults to IMMEDIATE.
object
Rollout strategy. CANARY needs exactly one of canaryPercentage or canaryCount. ROLLING needs exactly one of batchSize or wavePercentages. Fields of another strategy are rejected.
Percentage of instances to deploy as canary. CANARY only, alternative to canaryCount.
Absolute number of canary devices. CANARY only, alternative to canaryPercentage.
Minutes every canary device has to report installed before the rollout halts. Defaults to 30. CANARY only.
Whether to promote automatically after the validation period. CANARY only.
Minutes to wait before auto-promoting, if autoPromote is true. CANARY only.
Number of instances per wave. ROLLING only, alternative to wavePercentages.
Ordered wave sizes in percent of the targeted devices. For example [10] means 10% first, then the remaining 90%. Each value is 1-100 and the sum is at most 100. ROLLING only, alternative to batchSize.
Whether to progress to the next batch automatically. ROLLING only.
Minutes to wait before progressing to the next batch, if autoProgress is true. ROLLING only.
Rollback configuration. Defaults to disabled.
object
Whether auto-rollback is enabled
Type of threshold to use. Required when enabled is true.
Threshold value (percentage or count). Required when enabled is true and thresholdType is not NONE.
Skip the schedule check and deploy outside scheduled windows. Requires the override permission.
Reason for skipping the schedule check. Required if skipScheduleCheck is true.
Skip the scope limit check and exceed the user’s scope limit. Requires the override permission.
Reason for skipping the scope limit check. Required if skipScopeLimitCheck is true.
Skip the target permission check and deploy to devices outside the user’s target permissions. Requires the override permission.
Reason for skipping the target permission check. Required if skipTargetPermissionCheck is true.
ID of the user who performs the deployment (used for permission checks)
Group IDs of the user (used for permission checks)
Responses
Section titled “Responses”Deployment created successfully
object
object
Labels a device must carry (all must match)
object
Label expressions a device must satisfy (all must match)
object
Label key
Match operator
Label values (for In and NotIn)
Application parameter overrides
object
FM-1447: the revision number the deployment targets (1, then +1 per re-deploy). Set on the detail response only.
FM-846: the manifest deploymentProfiles[].id this deployment deploys; absent when the description declared nothing to choose between
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
The manifest deploymentProfiles[].id
Rc2 wire type of the profile’s own type; absent for an off-spec type
object
Component name
FM-1159: the grouping key shared by every deployment created from the same multi-profile submission; absent for an ungrouped deployment
FM-1159: every sibling row of this deployment group, including this one, in creation order. Absent when the deployment is ungrouped.
object
The deployment group id
All members including the deployment this group is attached to, in creation order
object
The manifest deploymentProfiles[].id this member deploys
FM-1362: the member’s profile summarised (type + components), when resolvable
object
The manifest deploymentProfiles[].id
Rc2 wire type of the profile’s own type; absent for an off-spec type
object
Component name
FM-1258: the operator-chosen Margo metadata.namespace; absent when the organization slug (tenant default) is used
FM-1201: the device groups targeted at create time (name snapshots)
object
Device group UUID; absent when the group was deleted
Name of the group when the deployment was created
True when the group no longer exists
The live group’s current name, when it differs from the snapshot
FM-1412: the deployment this one was split from, if any
FM-1484: when the deployment was deleted. Set while the removal is not finalised (status is REMOVING); the deployment is then read-only.
Priority (0-100)
object
Rollout strategy type
Current rollout phase
Rollout configuration (strategy-specific)
object
Rollback configuration (enabled, thresholdType, thresholdValue)
object
Current batch number (for rolling/canary)
Total number of batches
FM-1475: when the deployment last changed state (newest of creation, start, completion and any instance status-history entry). Set on list responses only.
object
Application version string
object
object
Digest of the bundle served to the device
Download progress in percent
Number of deploy attempts so far
FM-845: per-component states from the most recent status report. Empty until the device has reported.
object
Component name
Component state as reported by the device (rc2, lowercase)
object
Machine-readable error code
Component or subsystem that raised the error
Human-readable error message
FM-845: the structured status.error from the most recent report
object
Machine-readable error code
Component or subsystem that raised the error
Human-readable error message
Batch number for rolling updates (1-based)
Whether this instance is part of the canary group
FM-1301: when the operator removed the deployment from this device alone. The device stays excluded until it is re-included.
FM-1301: users.id of the operator who removed the deployment from this device
FM-1411: the Margo ApplicationDeployment.id the device knows this item by. Equals deploymentId unless the item was split off another deployment.
FM-1202: the targeted device groups that contained the device at create time
FM-1202: selected directly (device list or label selector)
object
Margo clientId the device authenticates with
Device display name
Device status
Recent status history entries for this instance (up to 10, newest first)
object
Status the instance moved to
Who or what reported the change
FM-845: per-component states reported at this point in time
object
Component name
Component state as reported by the device (rc2, lowercase)
object
Machine-readable error code
Component or subsystem that raised the error
Human-readable error message
FM-845: the structured top-level error reported at this point in time
object
Machine-readable error code
Component or subsystem that raised the error
Human-readable error message
Number of targeted instances
Number of instances in status INSTALLED
Number of instances in status FAILED
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" } ]}Bad request - Invalid deployment data
Unauthorized - Invalid or missing authentication
Forbidden — caller lacks required permission