---
title: "List rollback candidates"
method: GET
path: "/deployments/{id}/rollback-candidates"
tags: ["Deployments"]
---

# List rollback candidates

`GET /deployments/{id}/rollback-candidates`

## Request

- Base URL: `https://api.ravion.com`
- URL: `https://api.ravion.com/deployments/{id}/rollback-candidates`
- Auth: HTTP bearer

List past successful deployments eligible for rollback.

## Path parameters

- `id` string, required

## Response `200`

The request has succeeded.

- object
  - `data` DeploymentRollbackCandidate[], required
    - union: A past deployment eligible to be re-deployed. Discriminated by deployment kind so consumers can narrow on `kind` to access per-type fields without optionality games.
      - object: AWS ECS rollback candidate — carries task-definition fields the dialog needs to disambiguate revisions of the same family.
        - `createdAt` string, date-time, required: UTC RFC3339 timestamp with a required Z suffix
        - `deploymentId` string, required
        - `description` string, required
        - `imageRefs` string[], required: Absolute image references (`repo:tag` or `repo@sha256:...`) that the task definition references.
        - `kind` 'aws:ecs', required
        - `taskDefinitionArn` string, required: ECS task-definition ARN.
        - `taskDefinitionFamily` string, required: ECS task-definition family.
        - `taskDefinitionRevision` integer, required: ECS task-definition revision.
      - object: AWS EC2 rollback candidate. The release snapshot is intentionally summarized for display; the server reloads the authoritative snapshot when rollback is requested.
        - `commandCount` integer
        - `createdAt` string, date-time, required: UTC RFC3339 timestamp with a required Z suffix
        - `deploymentId` string, required
        - `description` string, required
        - `imageUri` string
        - `kind` 'aws:ec2', required
        - `runtime` 'CONTAINER' | 'MANUAL', required: Which runtime the deploy targets — drives which release fields on `AwsEc2DeploymentDefinition` carry values.
        - `sourceRef` string
        - `sourceRepo` string
      - object: AWS AMI rollback candidate. A rollback re-releases this deployment's images, so it is offerable only while its source image is still registered.
        - `createdAt` string, date-time, required: UTC RFC3339 timestamp with a required Z suffix
        - `deploymentId` string, required
        - `description` string, required
        - `kind` 'aws:ami', required
        - `publish` boolean, required: Whether that deployment published its images.
        - `regions` string[], required: Every region the deployment's images landed in.
        - `sourceAmiId` string, required: Home-region AMI id the rollback re-releases.
      - object: AWS static rollback candidate — carries the promoted S3 directory, which is the only thing the rollback re-applies.
        - `createdAt` string, date-time, required: UTC RFC3339 timestamp with a required Z suffix
        - `deploymentId` string, required
        - `description` string, required
        - `directory` string, required: Promoted S3 directory the rollback re-writes to the KVS `active` key.
        - `kind` 'aws:static', required
      - object: AWS EKS rollback candidate — carries the Helm revision the rollback reinstates, plus enough chart identity for the dialog to say what going back to it means. There is no image pre-check of the kind the ECS and EC2 candidates perform, and its absence is deliberate rather than missing: a Helm rollback replays a revision out of the cluster's OWN release history, so what makes a candidate valid is that the revision is still in that history — a fact the control plane cannot see and has no business guessing at. Helm itself refuses a revision it no longer holds, which is the check, performed by the only party that can perform it.
        - `chartName` string: Chart name installed by that revision.
        - `chartVersion` string: Chart version installed by that revision — the field that most often makes one candidate distinguishable from the next. There is deliberately no `appVersion` beside it: `EksDeploymentData` does not persist one, and a field the server could only ever leave empty is worse than an absent field, because a client is entitled to render it.
        - `createdAt` string, date-time, required: UTC RFC3339 timestamp with a required Z suffix
        - `deploymentId` string, required
        - `description` string, required
        - `isExternal` boolean: True when this revision was NOT put there by Ravion — somebody ran `helm upgrade` against the cluster and Operator's inventory found the revision afterwards. Offerable precisely because Helm's history does contain it: an external `helm upgrade` is a real point in the release's history and a rollback can return to it. The marker exists so the dialog can say so, because reinstating a state Ravion never chose is a different decision from reinstating one it did. A kubectl-shaped external change never reaches this list at all: it left no Helm revision, so it fails the `releaseRevision` rule above and there is nothing to offer.
        - `kind` 'aws:eks', required
        - `release` string: Release the revision belongs to, as `namespace/name`. Two module instances can share a chart, and the release is what tells them apart in the dialog.
        - `releaseRevision` integer, required: Helm's own revision number in the cluster's release history — not a Ravion identifier. This is the number the rollback is issued against, so a candidate without one is not offerable.
      - object: AWS Lambda rollback candidate — carries the published version the rollback re-points the deploy alias at. A published version is immutable (code + function configuration), so a rollback is an alias flip and nothing else. Image-packaged candidates are offered only when their deploy recorded the digest Lambda pinned for the version and that digest is not definitively missing from ECR.
        - `codeRef` string: S3 key (zip) or resolved image digest URI (image) of the version's code.
        - `createdAt` string, date-time, required: UTC RFC3339 timestamp with a required Z suffix
        - `deploymentId` string, required
        - `description` string, required
        - `functionName` string: Short function name.
        - `kind` 'aws:lambda', required
        - `packageType` 'ZIP' | 'IMAGE', required: Which packaging mode the deploy targets — drives which code-source fields on `AwsLambdaDeploymentDefinition` carry values.
        - `publishedVersion` string, required: Published function version the alias is flipped back to.

## Other responses

- `401`: You are not authenticated
- `403`: You do not have permission to access this resource.
- `404`: The server cannot find the requested resource.
- `500`: Server error

---

[API](https://skmtc.dev/ravion/apis/ravion.md) - [All operations](https://skmtc.dev/ravion/apis/ravion/llms.txt) - [OpenAPI document](https://skmtc.dev/ravion/apis/ravion/revisions/66e5732205a0?raw)