# Set a region's release policy

`PUT /apis/cra.diagrid.io/v1beta2/regions/{RegionId}/releasesubscription`

Choose the release channel a region follows, or hold its upgrades. Holding requires a reason and a review time, and the review time must be in the future and no more than 90 days away; reaching it does not resume upgrades, it marks the policy as needing a decision. Pinning a version, permitting a downgrade and setting freeze windows are reserved to Diagrid, and a value this request does not carry is preserved rather than cleared.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `RegionId` | string | Yes | Unique identifier of the region. |

### Request body

The release policy to apply.

`application/json`

A complete statement of the release policy a region administrator owns. Anything this request does not carry - a pinned version, freeze windows, downgrade permission - is preserved as it was rather than cleared.

- `channel` (string) — Required. The release channel the region should follow: `stable` or `candidate`. A channel you are not entitled to is refused, and the error names the channels you may choose.
- `mode` (string) — Required. `follow` to track the channel, `hold` to stay on the release the region is running. Pinning a version is reserved to Diagrid.
- `reason` (string) — Why upgrades are being held. Required when the mode is `hold`.
- `reviewAt` (string (date-time)) — When the hold must be reviewed. Required when the mode is `hold`. It must be in the future and no more than 90 days away. Reaching it does not resume upgrades; it marks the policy as needing a decision.

## Responses

### 200 — The region's release policy, as it now stands.

`application/json`

The release policy governing a region: which release channel it follows, and whether upgrades are currently held. Fields that only Diagrid can set - a pinned version, freeze windows and downgrade permission - are reported here so that a region which is not moving can be explained, but they cannot be changed through this API.

- `region` (string) — The region the policy governs.
- `component` (string) — The released component the policy is about.
- `channel` (string) — The release channel the region follows, such as `stable` or `candidate`.
- `mode` (string) — What the region is doing about its channel. `follow` tracks the channel, one tested upgrade at a time. `hold` keeps the region on the release it is running. `pin` holds it at a named version and is set only by Diagrid.
- `version` (string) — The pinned version. Present only when the mode is `pin`.
- `reason` (string) — Why upgrades were held or pinned. Present only for those modes.
- `reviewAt` (string (date-time)) — When the hold or pin must be reviewed. Reaching this time does not resume upgrades; it marks the policy as needing a decision.
- `decisionRequired` (boolean) — True when a hold or pin has reached its review time and is still in force. The region stays where it is until the policy is changed.
- `freezeWindows` (integer) — How many freeze windows the policy carries. A region inside a freeze window does not move, whatever the rest of the policy says.
- `allowDowngrade` (boolean) — Whether the policy permits moving the region to an older release.

### 403 — You are not authorized to perform this action, or the change is one only Diagrid can make.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.

### 404 — The region was not found, or has no release policy yet.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.