List deployments

GET

/api/v1/deployments

const url = 'http://localhost:3000/api/v1/deployments?status=PENDING&strategy=IMMEDIATE&createdFrom=2026-01-01&createdTo=2026-01-31&limit=20&offset=0';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/deployments?status=PENDING&strategy=IMMEDIATE&createdFrom=2026-01-01&createdTo=2026-01-31&limit=20&offset=0' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves a paginated list of deployments with optional filtering by status, name, search, device, application version, application, rollout strategy and creation date range.

Authorizations

api-key
bearer

Parameters

Query Parameters

status

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

Filter by deployment status

search

string

Search in deployment name and status message

name

string

Filter by deployment name (contains, case-insensitive)

deviceId

string format: uuid

Only deployments that have an instance targeting this device

applicationDescriptionId

string format: uuid

Only deployments of this application description (version)

applicationPackageId

string format: uuid

Only deployments whose application description belongs to this application

strategy

string

Allowed values: IMMEDIATE CANARY ROLLING

Filter by rollout strategy

createdFrom

string

Example

2026-01-01

Inclusive lower bound on createdAt. ISO 8601 YYYY-MM-DD (00:00 UTC) or a date-time with a zone.

createdTo

string

Example

2026-01-31

Inclusive upper bound on createdAt. A date-only value (YYYY-MM-DD) includes the whole UTC day. createdFrom later than createdTo is rejected with 400.

limit

number

default: 20 >= 1 <= 100

Page size

offset

number

Number of results to skip

cursor

string

Cursor for pagination

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.

Responses

200

List of deployments retrieved successfully

application/json

object

data

required

Array<object>

object

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

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

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

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

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

required

string format: uuid

version

required

Application version string

string

applicationPackage

object

required

string format: uuid

name

required

string

instanceCount

Number of targeted instances

number

runningInstances

Number of instances in status INSTALLED

number

failedInstances

Number of instances in status FAILED

number

instances

Array<object>

object

required

string format: uuid

status

required

string

Allowed values: PENDING INSTALLING INSTALLED FAILED REMOVING REMOVED

componentStatuses

required

Always empty in the list; the detail response carries the component states.

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

excludedAt

FM-1301: when the operator removed the deployment from this device alone.

string format: date-time

total

required

Total number of deployments matching the filter

number

hasMore

required

True when more deployments follow this page

boolean

nextCursor

Cursor for the next page

string

Example

{
  "data": [
    {
      "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 - a query parameter is malformed, or createdFrom is after createdTo

401

Unauthorized - Invalid or missing authentication

403

Forbidden — caller lacks required permission

503

Service unavailable - Deployment service is not reachable