# Get a release

Source: https://www.jawsdeploy.net/rest-api/releases-details | Section: Releases

Read one release with the snapshot it will deploy - packages, steps, variables and lifecycle phases.

`GET /api/release/details`

Returns a single release together with the snapshot it locked in when it was created: the package versions chosen, the deployment plan (steps) as it stood, the variables as they stood, and where the release currently sits in its lifecycle.

There are **two ways to name the release**, because both are what a caller actually holds:

- `releaseId` - what [Create a release](https://www.jawsdeploy.net/rest-api/releases-create) handed back to the job that cut it.
- `projectId` together with `version` - what a later job usually knows, having only ever asked for a version.

Give one or the other. Sending neither is a `400`. `version` is matched exactly first and then as a SemVer equivalent, so `6.1` finds a release stored as `6.1.0` and a caller does not have to guess which spelling the build system used.

Deployments are not part of this response. A release can be deployed any number of times, so its deployments are a paged list in their own right - [List deployments](https://www.jawsdeploy.net/rest-api/deployments-list) - and the status and logs of a single deployment are on [Get deployment status](https://www.jawsdeploy.net/rest-api/deployments-status).

Parts of the snapshot are secrets and do not leave the server - see below.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `releaseId` | query | string | no | ID of the release. Give this, **or** `projectId` and `version` together. |
| `projectId` | query | string | no | ID of the project. Only meaningful together with `version`, and ignored when `releaseId` is given. |
| `version` | query | string | no | The release version within that project. Only meaningful together with `projectId`. Matched exactly first, then as a SemVer equivalent - `6.1` finds `6.1.0`. |

### Secrets in the snapshot

A release snapshot holds things that must not leave the server, and three of them are withheld here. There is no parameter that turns any of it off.

- **Variable values** are masked whenever the snapshot encrypted them or the variable is typed `Secret`. The value reads back as •••••• with `isSecret` set to `true` - the same test and the same mask the rest of Jaws applies before showing a value.
- **Step scripts** are omitted entirely. A script can carry a literal credential, and a full script body would dominate the response besides. `hasScript` says whether the step has one.
- **Step property values** are omitted entirely. Step template properties include `SecureString` controls, and nothing here could reliably tell a credential apart from an ordinary setting. `hasProperties` says whether the step has any.

### Step fields

A release step is a copy of the project step as it stood when the release was cut, so changing the project afterwards does not change what this release will run.

`runOn` is `TargetMachine`, `Worker` or `WorkerToCloudTargets`.

`scriptLanguage` is `powershell` (PowerShell 7), `powershell5` (Windows PowerShell 5.1), `python` or `json`.

`ignoreErrors` is the snapshot of the project step's `errorAction`: `true` is `Continue`, `false` is `Stop`. `onStepFailure` (`ContinueToNextStep` or `StopDeployment`) and `runAfterStop` are the separate question of what a failed step does to the rest of the deployment - see [Update a project step](https://www.jawsdeploy.net/rest-api/project-step-update) for how the two interact.

`machineOrder` (`MachineName` or `TagPriority`), `onMachineFailure` (`ContinueToOtherMachines` or `StopStep`) and `waitBetweenMachineGroups` describe the rolling behaviour; `isRolling` and `rollingGroupId` say whether the step is part of a [rolling group](https://www.jawsdeploy.net/rest-api/rolling-groups-list), and that id names the snapshotted group, not the project's.

### Lifecycle phases

`phases` is empty for a release whose channel binds no lifecycle - such a release can be deployed to any environment its project reaches.

Where there is a lifecycle, each phase reports whether it `isAvailable` (the release may be deployed into it now), whether it `isCompleted`, whether it `isOptional`, and how many of its `deploymentsRequired` have been completed so far. `howToTrigger` on a phase environment is `Manual` or `Automatic` - `Automatic` is an environment a completed preceding phase deploys into on its own.

This is the same progression that decides whether a deploy is allowed, so reading it first tells you what [Deploy a release](https://www.jawsdeploy.net/rest-api/releases-deploy) will accept: an environment blocked by phase progression is refused there with `some environments are not available`.

## Response fields

| Field | Type | Description |
|---|---|---|
| `releaseId` | string | The release's id. |
| `projectId` | string | The project the release belongs to. |
| `projectName` | string | That project's name as it reads now, not as it read when the snapshot was taken. |
| `workspaceId` | string | The workspace the project belongs to. |
| `version` | string | The release version, as it was stored. |
| `notes` | string | The release notes, or `null`. |
| `metadata` | object | The free-form document attached at creation, exactly as it was stored, or `null`. See [Create a release](https://www.jawsdeploy.net/rest-api/releases-create). |
| `created` | string | When the release was created, ISO 8601 with offset. |
| `createdBy` | object | Who created it: `userId`, `name`, `email`. `null` when the creator no longer resolves. |
| `channelId` | string | The channel the release is bound to, or `null`. |
| `channelName` | string | Name of that channel, or `null`. |
| `lifecycleName` | string | Name of the lifecycle the channel binds the release to, or `null` when the release is not phase-controlled. |
| `packages` | object[] | The package versions the release pinned. Empty when the project has no packages. |
| `packages[].feedId` | string | The feed the package is pulled from. |
| `packages[].packageId` | string | The package id. |
| `packages[].packageType` | string | The package type - see [Package types and naming](https://www.jawsdeploy.net/rest-api/package-types). |
| `packages[].version` | string | The exact version pinned into this release. |
| `steps` | object[] | The deployment plan as it stood when the release was cut, ordered by `order`. |
| `steps[].releaseStepId` | string | Id of the snapshotted step. Distinct from the project step it was copied from. |
| `steps[].originalStepId` | string | Id of the project step it was copied from, which may since have changed or been deleted. |
| `steps[].order` | integer | Position in the plan. Steps are returned in this order. |
| `steps[].name` | string | Step name. This is what [Deploy a release](https://www.jawsdeploy.net/rest-api/releases-deploy) matches `excludeStepNames` against. |
| `steps[].description` | string | Step description, or `null`. |
| `steps[].runOn` | string (enum) | `TargetMachine`, `Worker` or `WorkerToCloudTargets`. |
| `steps[].scriptLanguage` | string (enum) | `powershell`, `powershell5`, `python` or `json`. |
| `steps[].hasScript` | boolean | Whether the step has a script body. The body itself is never returned. |
| `steps[].hasProperties` | boolean | Whether the step has step-template property values. The values themselves are never returned. |
| `steps[].ignoreErrors` | boolean | The snapshot of the step's `errorAction`: `true` is `Continue`, `false` is `Stop`. |
| `steps[].environmentIds` | string[] | Environments the step is restricted to. Empty means every environment of the deployment. |
| `steps[].machineNameFilter` | string[] | Machine filter carried into the snapshot. Empty means no filter. |
| `steps[].workerTagId` | string | Tag identifying the worker pool, or `null`. |
| `steps[].parallelMachines` | integer | How many machines the step runs on at once. |
| `steps[].parallelCloudTargets` | integer | How many cloud targets the step runs on at once, or `null`. |
| `steps[].isRolling` | boolean | Whether the step is part of a rolling group. |
| `steps[].rollingGroupId` | string | The snapshotted rolling group the step belongs to, or `null`. Not the project's group id. |
| `steps[].machineOrder` | string (enum) | `MachineName` or `TagPriority`. |
| `steps[].onMachineFailure` | string (enum) | `ContinueToOtherMachines` or `StopStep`. |
| `steps[].onStepFailure` | string (enum) | `ContinueToNextStep` or `StopDeployment`. |
| `steps[].runAfterStop` | boolean | Whether the step still runs after an earlier step stopped the deployment. |
| `steps[].onNoTargets` | string (enum) | `Skip`, `Warn` or `Fail` - what the step does when no target matches its filters. |
| `steps[].waitBetweenMachineGroups` | boolean | Whether each tag rank finishes before the next one starts. |
| `variables` | object[] | The variables as they stood when the release was cut, ordered by name. Secret values are masked. |
| `variables[].name` | string | Variable name, as referenced from scripts and step properties. |
| `variables[].description` | string | Variable description, or `null`. |
| `variables[].type` | string | `Text`, `Secret`, `Script`, `Number`, `Boolean`, `Date`, `Map` or `Json`. |
| `variables[].values` | object[] | The scoped values of the variable. |
| `variables[].values[].value` | string | The value, or the mask when it is a secret. |
| `variables[].values[].isSecret` | boolean | `true` when the value was masked - set when the snapshot encrypted it or the variable is typed `Secret`. |
| `variables[].values[].environmentsFilter` | string[] | Environments this value applies to. Empty means all. |
| `variables[].values[].machineFilter` | string[] | Machines this value applies to. Empty means all. |
| `variables[].values[].cloudTargetFilter` | string[] | Cloud targets this value applies to. Empty means all. |
| `variables[].values[].stepFilter` | string[] | Steps this value applies to. Empty means all. |
| `phases` | object[] | Where the release sits in its lifecycle, ordered by `sortOrder`. Empty when the release is not phase-controlled. |
| `phases[].phaseId` | string | Id of the snapshotted phase. |
| `phases[].name` | string | Phase name. |
| `phases[].sortOrder` | integer | Position in the lifecycle. Phases are returned in this order. |
| `phases[].isAvailable` | boolean | Whether the release may be deployed into this phase's environments now. |
| `phases[].isCompleted` | boolean | Whether the phase's progress requirement has been met. |
| `phases[].isOptional` | boolean | Whether the phase can be skipped without blocking the ones after it. |
| `phases[].isAnyDeploymentRunning` | boolean | Whether a deployment into this phase is in flight, or `null` when that is not known. |
| `phases[].deploymentsRequired` | integer | How many completed deployments the phase needs before it counts as completed. |
| `phases[].deploymentsCompleted` | integer | How many it has had. |
| `phases[].environments` | object[] | The environments in the phase. |
| `phases[].environments[].environmentId` | string | The environment's id. |
| `phases[].environments[].environmentName` | string | The environment's name. |
| `phases[].environments[].howToTrigger` | string (enum) | `Manual` or `Automatic`. An `Automatic` environment is deployed into on its own once the preceding phase completes. |
| `phases[].environments[].deploymentsCompleted` | integer | How many deployments of this release into this environment have completed. |

## Errors

| Status | Meaning |
|---|---|
| 400 | Neither a `releaseId` nor a `projectId` and `version` pair was given - the response reads `a release ID, or a project ID together with a version, is required`. |
| 400 | Invalid `releaseId`. A release in another organization is reported the same way as one that does not exist, so an id cannot be probed for existence. |
| 400 | Invalid `projectId`, or no release with that `version` exists for the project. |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks permission to view releases of this project. |

Example request:

```
GET /api/release/details?releaseId=rel_9f4c HTTP/1.1
Host: app.jawsdeploy.net
Authorization: Basic <base64(serviceAccountId:apiKey)>

// or, when only the version is known:
GET /api/release/details?projectId=prj_abc123&version=2.5.3 HTTP/1.1
```

Example response:

```
{
  "releaseId": "rel_9f4c",
  "projectId": "prj_abc123",
  "projectName": "Acme Web",
  "workspaceId": "ws_abc",
  "version": "2.5.3",
  "notes": "Build #4821 from main",
  "metadata": {
    "buildUrl": "https://ci.example/build/4821",
    "commit": "3f9a1c2"
  },
  "created": "2026-09-05T09:14:22.418+00:00",
  "createdBy": {
    "userId": "usr_ci",
    "name": "Build agent",
    "email": "ci@example.com"
  },
  "channelId": "chn_stable",
  "channelName": "Stable",
  "lifecycleName": "Default lifecycle",
  "packages": [
    {
      "feedId": "fd_internal",
      "packageId": "Acme.Web",
      "packageType": "nuget",
      "version": "2.5.3"
    }
  ],
  "steps": [
    {
      "releaseStepId": "rstp_01",
      "originalStepId": "stp_01",
      "order": 1,
      "name": "Deploy website",
      "description": null,
      "runOn": "TargetMachine",
      "scriptLanguage": "powershell",
      "hasScript": true,
      "hasProperties": true,
      "ignoreErrors": false,
      "environmentIds": [],
      "machineNameFilter": [],
      "workerTagId": null,
      "parallelMachines": 2,
      "parallelCloudTargets": null,
      "isRolling": true,
      "rollingGroupId": "rrg_web",
      "machineOrder": "MachineName",
      "onMachineFailure": "StopStep",
      "onStepFailure": "StopDeployment",
      "runAfterStop": false,
      "onNoTargets": "Skip",
      "waitBetweenMachineGroups": false
    }
  ],
  "variables": [
    {
      "name": "ConnectionString",
      "description": "Database connection",
      "type": "Secret",
      "values": [
        {
          "value": "••••••",
          "isSecret": true,
          "environmentsFilter": ["env_prod"],
          "machineFilter": [],
          "cloudTargetFilter": [],
          "stepFilter": []
        }
      ]
    }
  ],
  "phases": [
    {
      "phaseId": "rph_01",
      "name": "Test",
      "sortOrder": 1,
      "isAvailable": true,
      "isCompleted": true,
      "isOptional": false,
      "isAnyDeploymentRunning": false,
      "deploymentsRequired": 1,
      "deploymentsCompleted": 1,
      "environments": [
        {
          "environmentId": "env_test",
          "environmentName": "Test",
          "howToTrigger": "Automatic",
          "deploymentsCompleted": 1
        }
      ]
    }
  ]
}
```