# Client API: Deployments: Releases

> The 7 Client API operations for releases.

Source: https://www.coritan.com/docs/api/reference/client/deployments/deployments-releases/

Part of [Deployments](/docs/api/reference/client/deployments/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/deployments/{deployment_uuid}/releases`](#op-get-api-v1-client-deployments-deployment-uuid-releases) | The deployment's releases, newest first, production and preview alike |
| POST | [`/api/v1/client/deployments/{deployment_uuid}/releases`](#op-post-api-v1-client-deployments-deployment-uuid-releases) | Create release |
| GET | [`/api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}`](#op-get-api-v1-client-deployments-deployment-uuid-releases-release-uuid) | One release with each of its instances (instancelist) |
| POST | [`/api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/cancel`](#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-cancel) | Cancel release |
| GET | [`/api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/log`](#op-get-api-v1-client-deployments-deployment-uuid-releases-release-uuid-log) | The end of the release's build log, secrets redacted as it was written |
| POST | [`/api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/promote`](#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-promote) | Promote release |
| POST | [`/api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/rollback`](#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-rollback) | Rollback release |

### The deployment's releases, newest first, production and preview alike {#op-get-api-v1-client-deployments-deployment-uuid-releases}

`GET /api/v1/client/deployments/{deployment_uuid}/releases`

The deployment's releases, newest first, production and preview
alike. A template has none.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `limit` | query | integer | no | How many releases to return, 1 to 100 Default: `20`. |
| `offset` | query | integer | no | How many to skip, for the next page Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create release {#op-post-api-v1-client-deployments-deployment-uuid-releases}

`POST /api/v1/client/deployments/{deployment_uuid}/releases`

Release: a deployment built from git builds ``git_ref`` (its branch
when left out); an image deployment runs ``image_ref`` (its own when
left out). A branch for an image deployment, or an image for one built
from git, is refused with ``source_mismatch``.

A release of another branch than the production branch is a preview,
as a push of it is (``environment`` says otherwise): it gets its own
addresses and leaves production as it is, and is refused as a push's
preview would be (``previews_refused``, 402 when the plan has none,
409 when previews are off).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `git_ref` | string or null | no | Branch, tag or commit; the deployment's branch when left out |
| `git_sha` | string or null | no |  |
| `image_ref` | string or null | no | An image deployment's reference; its own when left out |
| `environment` | string, one of `production`, `preview` or null | no | production or preview, for a deployment built from git. Left out: another branch than the production branch makes a preview, as a push does; the production branch, a commit or a tag releases to production. A preview needs a branch other than the production branch |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One release with each of its instances (instancelist) {#op-get-api-v1-client-deployments-deployment-uuid-releases-release-uuid}

`GET /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}`

One release with each of its instances (``instance_list``). A release
of another deployment answers 404.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `release_uuid` | path | string (uuid) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel release {#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-cancel}

`POST /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/cancel`

Cancel a release still queued, building or deploying: its build
stops and its instances are removed, and the release that serves goes
on serving. One that has finished answers 409.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `release_uuid` | path | string (uuid) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The end of the release's build log, secrets redacted as it was written {#op-get-api-v1-client-deployments-deployment-uuid-releases-release-uuid-log}

`GET /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/log`

The end of the release's build log, secrets redacted as it was
written. A release of an image has none.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `release_uuid` | path | string (uuid) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Promote release {#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-promote}

`POST /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/promote`

A new production release of a ready preview's build (its image, its
static output or both), with nothing built again. The preview keeps
serving at its own addresses. 409 ``not_preview`` for a production
release: roll back to it instead.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `release_uuid` | path | string (uuid) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rollback release {#op-post-api-v1-client-deployments-deployment-uuid-releases-release-uuid-rollback}

`POST /api/v1/client/deployments/{deployment_uuid}/releases/{release_uuid}/rollback`

A new release of this earlier ready release's build, with nothing
built again: its files for a static site, its image for a web service,
both for a hybrid site. A static site's release serves at once; for the
others, the earlier release's instances that still have their servers
are started again instead of placed. 409 ``output_not_stored`` for a
release with static output made more than
``app.apps.static.RETENTION_DAYS`` ago, whose files may be gone (deploy
its commit again instead), 409 ``not_rollbackable`` for a release that
was never ready or holds nothing to serve, 409 ``already_current`` for
the release that serves now.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `release_uuid` | path | string (uuid) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |