# Client API: Deployment servers: Releases

> The 5 Client API operations for releases.

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

Part of [Deployment servers](/docs/api/reference/client/deployment-servers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/releases`](#op-get-api-v1-client-servers-uuid-releases) | List the server's releases |
| POST | [`/api/v1/client/servers/{uuid}/releases`](#op-post-api-v1-client-servers-uuid-releases) | Deploy a commit to the server |
| GET | [`/api/v1/client/servers/{uuid}/releases/{release_uuid}`](#op-get-api-v1-client-servers-uuid-releases-release-uuid) | Read one release with its log |
| POST | [`/api/v1/client/servers/{uuid}/releases/{release_uuid}/cancel`](#op-post-api-v1-client-servers-uuid-releases-release-uuid-cancel) | Cancel a release before it changes the server |
| POST | [`/api/v1/client/servers/{uuid}/releases/{release_uuid}/rollback`](#op-post-api-v1-client-servers-uuid-releases-release-uuid-rollback) | Roll the server back to an earlier release |

### List the server's releases {#op-get-api-v1-client-servers-uuid-releases}

`GET /api/v1/client/servers/{uuid}/releases`

List the server's releases.

Newest first, with what the server clones. ``git`` is the repository (never with a credential), its ``branch``,
whether a repository token is set (``token_set``) and whether releases
apply (``releases``); when they do not, ``reason`` says why, and ``git``
is null for a server that clones nothing. ``can.deploy`` says whether a
release may start now, with the ``error`` and ``reason`` when not.
``current_release`` is the live release and ``in_flight`` the one on its
way, each null when there is none.

Each release has ``status`` (``queued``, ``building`` while the commit is
fetched, ``deploying``, ``ready``, ``failed``, ``canceled`` or
``superseded``), ``trigger`` (``manual``, ``rebuild``, ``rollback`` or
``install``), ``source`` (``git``, ``redeploy`` or ``rollback``), the
commit (``git_ref``, ``git_sha``, ``commit_message``, ``commit_author``),
``is_current``, ``can_rollback``, ``can_cancel``, and for a failed one
``error``, ``error_code`` and ``restored`` (true when it had changed files
and the previous version was put back). Needs software.read.

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Deploy a commit to the server {#op-post-api-v1-client-servers-uuid-releases}

`POST /api/v1/client/servers/{uuid}/releases`

Deploy a commit to the server.

Starts a release of the newest commit of the server's branch, or of the
branch, tag or commit ``git_ref`` names. The platform fetches and checks the commit before the server is touched. The
server then stops, the repository's files are replaced, and it starts
again when it was running. If it does not stay up, the previous version is
put back. Files the repository does not hold are left alone. When the
server already runs that commit, the release ends ``canceled`` with
``error_code`` ``already_current`` and nothing changes.

Answers 201 with the queued ``release``. 409 with ``error``
``no_git_source`` (the server clones nothing the platform can fetch),
``release_in_progress``, ``server_busy`` (installing, transferring,
restoring or suspended), ``install_in_progress``, ``snapshot_in_progress``
or ``server_locked``; 422 ``invalid_ref`` for a ``git_ref`` that is not a
branch, tag or commit name. Needs software.update.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `git_ref` | string or null | no | A branch, a tag or a commit of the repository to release. Left out, the newest commit of the server's branch (its GIT_BRANCH variable, main when that is empty) |

#### Responses

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

### Read one release with its log {#op-get-api-v1-client-servers-uuid-releases-release-uuid}

`GET /api/v1/client/servers/{uuid}/releases/{release_uuid}`

Read one release with its log.

``log`` holds each step it took, what it left out and, for one that failed
to start, the server's last output. ``origin`` is the
release whose stored files a rollback or a redeploy runs. A release of
another server answers 404. Needs software.read.

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

#### Parameters

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

#### Responses

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

### Cancel a release before it changes the server {#op-post-api-v1-client-servers-uuid-releases-release-uuid-cancel}

`POST /api/v1/client/servers/{uuid}/releases/{release_uuid}/cancel`

Cancel a release before it changes the server.

A release that is queued or still being fetched can be cancelled. Nothing
on the server has changed at that point. 409 ``not_cancelable`` for one that is
replacing files (it finishes, or puts the previous version back, on its
own), one that has ended, and the release an install makes. Needs
software.update.

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

#### Parameters

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

#### Responses

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

### Roll the server back to an earlier release {#op-post-api-v1-client-servers-uuid-releases-release-uuid-rollback}

`POST /api/v1/client/servers/{uuid}/releases/{release_uuid}/rollback`

Roll the server back to an earlier release.

Starts a release of the earlier release's stored files. Nothing is fetched
from the git host, so it works while the host is down or the token has
expired.

Answers 201 with the new ``release`` (``trigger`` ``rollback``). 409
``already_current`` for the live release, ``not_rollbackable`` for one
that was never live, ``archive_not_stored`` for one whose files are no
longer kept (deploy its commit instead), and the refusals of Deploy.
Needs software.update.

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

#### Parameters

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

#### Responses

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