# Create a project channel

Source: https://www.jawsdeploy.net/rest-api/project-channel-create | Section: Project Channels

Create a new channel for a project, optionally gating which release and package versions it accepts.

`POST /api/project/channel`

Creates a new channel. If `isDefault` is true the previous default is cleared.

All rule fields are optional; omit them all to create an unrestricted channel.

### How the rules are evaluated

A channel gates two things, and each is optional - a blank field means *no constraint*.

- The **release version rule** (`versionRange`, `versionTagRegex`) gates which release versions may be created in the channel.
- The **package rules** (`packageRules`) gate which package versions may be pinned into those releases.

`versionRange` bounds the version **number** and takes no account of the prerelease tag; `versionTagRegex` decides whether tagged versions are allowed at all. The endpoints of a range therefore compare on the number alone, so `[2.0,4.0)` accepts `2.0.0-beta` and rejects `4.0.0-beta`. This differs from raw NuGet range semantics, which sort a prerelease below its own release.

`versionTagRegex` is matched against the prerelease label **without** the leading `-`, and against an empty string for a stable version. So `^$` accepts stable versions only, `^.+$` accepts prereleases only, and `^beta.*$` accepts `2.1.0-beta3` but not `2.1.0` or `2.1.0-rc1`. The app's channel editor shows `^$` as *Stable only* and `^.+$` as *Prereleases only*; any other expression shows as a custom pattern. There is no separate mode field to set.

`packageRules` are evaluated **in order and the first rule whose `packageFilter` matches a package wins**; a package matched by no rule is unconstrained. Each filter may only be used once per channel.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | ID of the project. |
| `name` | body | string | yes | Channel name. Must be unique within the project. Max 200 characters. |
| `description` | body | string | no | Optional description. |
| `lifecycleId` | body | string | no | Lifecycle to bind to this channel. Must exist in the project's workspace. |
| `isDefault` | body | boolean | no | Mark as the project's default channel. |
| `versionRange` | body | string | no | Version range a release version must satisfy, e.g. `[2.0,3.0)`. Bounds the version number only. Blank for any version. |
| `versionTagRegex` | body | string | no | Regular expression the release version's prerelease tag must match, e.g. `^beta.*$`. Use `^$` for stable versions only, `^.+$` for prereleases only. Blank for any tag. |
| `versionDefaultTag` | body | string | no | Prerelease tag appended to versions auto-suggested for this channel, e.g. `beta`. Must itself match `versionTagRegex`. Blank to suggest plain version numbers. |
| `packageRules` | body | array<object> | no | Ordered list of package version rules. Evaluated in array order; the first matching `packageFilter` wins. |
| `packageRules[].packageFilter` | body | string | yes | Package ID glob, e.g. `*` or `MyApp.*`. Case insensitive; `*` and `?` are the only wildcards and every other character is literal. Required on each rule - use `*` to match all packages. Max 500 characters. |
| `packageRules[].versionRange` | body | string | no | Version range the package version must satisfy, e.g. `[2.0,3.0)`. Blank for any version. |
| `packageRules[].versionTagRegex` | body | string | no | Regular expression the package version's prerelease tag must match, e.g. `^$` for stable versions only. Blank for any tag. |

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid `projectId`, or a duplicate channel name. |
| 400 | Validation failure. Rule fields are validated on save: an unparseable `versionRange`, an invalid `versionTagRegex` (backreferences and lookarounds are rejected), a `versionDefaultTag` which its own `versionTagRegex` would not match, a blank `packageFilter`, or two package rules sharing the same filter. |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks the required role. |

Example request:

```
POST /api/project/channel
Authorization: Basic <base64(serviceAccountId:apiKey)>
Content-Type: application/json

{
  "projectId": "prj_abc123",
  "name": "Beta",
  "lifecycleId": "lc_preview",
  "versionTagRegex": "^beta.*$",
  "versionDefaultTag": "beta",
  "packageRules": [
    {
      "packageFilter": "MyApp.Frontend",
      "versionRange": "[2.0,3.0)"
    },
    {
      "packageFilter": "*",
      "versionTagRegex": "^$"
    }
  ]
}
```

Example response:

```
{ "channelId": "ch_2" }
```