# Organization API: Organization deployments: Canary

> The 4 Organization API operations for canary.

Source: https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments-canary/

Part of [Organization deployments](/docs/api/reference/organizations/organization-deployments/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-canary) | Get canary |
| PUT | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary`](#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-canary) | Start or change a canary |
| POST | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary/abort`](#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-canary-abort) | Abort canary |
| POST | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary/promote`](#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-canary-promote) | Promote canary |

### Get canary {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-canary}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary`

The production release that takes a share of the traffic beside the
current one (null without one): its share, its status, and whether it
serves yet (``serving``; until it does the current release takes
everything). ``current`` is the current release.

#### Parameters

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

#### Responses

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

### Start or change a canary {#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-canary}

`PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary`

Give a production release newer than the current one, on its way or
ready, ``traffic_percent`` (1 to 99) of the traffic; without
``release``, change the share of the release that holds one. A visitor
stays on the release they got for an hour. 404 for a release that is
not the deployment's, or no canary; 409 as ``detail.error`` says
(``no_current``, ``release_current``, ``release_preview``,
``release_not_live``, ``release_older``, ``canary_exists``,
``app_not_active``).

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `release` | string (uuid) or null | no | Left out: the release that holds a share now |
| `traffic_percent` | integer | yes |  |

#### Responses

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

### Abort canary {#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-canary-abort}

`POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary/abort`

Take the canary's share away and end it: the current release takes
all the traffic, and the canary's instances leave after the drain
window. ``release`` as for promote. 404 without a canary.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `release` | string (uuid) or null | no | The canary meant; 409 when another holds the share |

#### Responses

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

### Promote canary {#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-canary-promote}

`POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/canary/promote`

Make the canary the current release: it takes all the traffic, and
the release it shared with is superseded and leaves service after the
drain window. ``release`` guards against acting on a canary that
changed since it was read (409 ``canary_changed``). 404 without a
canary; 409 ``canary_not_ready`` while it is still deploying.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `release` | string (uuid) or null | no | The canary meant; 409 when another holds the share |

#### Responses

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