# Create a workspace

Source: https://www.jawsdeploy.net/rest-api/workspaces-create | Section: Workspaces

Create a workspace, optionally pinned to a package store location.

`POST /api/workspace`

Creates a workspace in the organization the service account belongs to.

Pass `regionId` to choose the **package store location** - the region whose blob storage holds this workspace's Jaws-feed packages (list the options with [List package store locations](https://www.jawsdeploy.net/rest-api/workspaces-list-regions)). Omit it (or send `null`) to use the default location, which keeps the classic behaviour.

The package store location is **fixed at creation and cannot be changed afterwards** - stored packages physically live in that region's storage account, so moving a workspace would mean copying every package across regions. Choose based on where the workspace's **deployment targets** live, not where the operator sits.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | body | string | yes | Display name of the workspace. |
| `slug` | body | string | no | URL-friendly identifier; generated from the name when omitted. |
| `description` | body | string | no | Optional free-text description. |
| `regionId` | body | string | no | Package store location ID. Omit/null for the default location. Fixed at creation. |
| `variableSyntaxMode` | body | string | no | Variable substitution syntax: `Legacy` preserves plain-token behavior; `Extended` enables filters and conditionals. Omit/null to use `Extended`. |

## Errors

| Status | Meaning |
|---|---|
| 401 | Missing or invalid Basic auth credentials, or the service account lacks permission to add workspaces in this organization. |
| 422 | Validation failed - e.g. a missing name, a duplicate slug, or a `regionId` that is not an active package store location. |

Example request:

```
POST /api/workspace HTTP/1.1
Authorization: Basic <base64(...)>
Content-Type: application/json

{
  "name": "Sydney",
  "slug": "sydney",
  "description": "AU workloads",
  "regionId": "au",
  "variableSyntaxMode": "Extended"
}
```

Example response:

```
{
  "workspaceId": "ws_syd",
  "name": "Sydney",
  "slug": "sydney",
  "regionId": "au",
  "regionName": "Australia",
  "variableSyntaxMode": "Extended"
}
```