# Create a workspace

Create a workspace on behalf of the current identity and return the new workspace ID.

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces
```

## Before you call this API

Choose a name for the new workspace. Prepare a personal access token and the name.

The following example uses:

- `$AI_STUDIO_API_KEY`: Your personal access token, passed in the `X-API-Key` header.
- `$WORKSPACE_NAME`: The name of the workspace to create, passed in the request body's `name` field.

A workspace name cannot be empty. The service ignores leading and trailing whitespace in the name.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'$WORKSPACE_NAME'"
  }'
```

## Request body

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name of the workspace to create. |

## Successful response

On success, the API returns `200`. `data.id` is the new workspace ID.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "ws_01"
  }
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.id` | string | ID of the new workspace. |

## Error response

```json
{
  "code": "ErrWorkspaceAlreadyExists",
  "msg": "Workspace already exists",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status
  - Error code
  - Common cause
  - Recommended action
* - `400`
  - `ErrParamInvalid` or `INVALID_ARGUMENT`
  - `name` is missing, empty, or does not meet the requirements.
  - Provide a non-empty workspace name and retry.
* - `401`
  - `Unauthorized` or `UNAUTHENTICATED`
  - Credentials are missing or invalid.
  - Check the personal access token.
* - `403`
  - `ErrUserNotSynced` or `PERMISSION_DENIED`
  - The current identity has not been synchronized or cannot create workspaces.
  - Complete account synchronization, or ask an administrator for access before retrying.
* - `409`
  - `ErrWorkspaceCreating` or `ErrWorkspaceAlreadyExists`
  - A workspace with the same name is being created or already exists.
  - Wait for the pending creation to finish, or use another name.
* - `410`
  - `ErrWorkspaceRolledBack`
  - An earlier creation was rolled back.
  - Check the creation conditions and retry with a new request.
* - `500`
  - `ErrWorkspaceCreateFailed` or `ErrWorkspaceManualIntervention`
  - The service could not create the workspace.
  - Record the request time and error message, then contact an administrator.
```