# Submit a workspace-creation task

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Submit an asynchronous workspace-creation task. When the request is accepted, the API immediately returns a task record; it does not wait for the workspace to be created in this response.

The current console uses this API to create workspaces. To wait synchronously for the creation result, use [Create a workspace](create-workspace.md#request-body).

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

## Before you call

Determine the new workspace name. Prepare a [personal access token](../../../../guides/genesis/api-keys.md#create-and-manage-personal-access-tokens). You do not need to enter a workspace before calling this API.

## Request body

Replace `$AI_STUDIO_API_KEY` and `$WORKSPACE_NAME` with actual values.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Input example

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

:::::
:::::{tab-item} Parameter details

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name of the workspace to create. It cannot be empty after trimming leading and trailing whitespace. |

:::::
::::::
:::::::

## Successful response

On success, the API returns 202. `data` is the creation task submitted by this request, not a completed workspace.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "creation_01",
    "name": "Analytics workspace",
    "status": "pending",
    "created_at": "2026-08-28T09:00:00Z",
    "updated_at": "2026-08-28T09:00:00Z"
  }
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.id` | string | Workspace-creation task ID. |
| `data.name` | string | Name of the workspace to create. |
| `data.status` | string | Task status: `pending`, `running`, `succeeded`, `failed`, or `cleanup_pending`. |
| `data.workspace_id` | string | Created workspace ID. Omitted if creation has not succeeded. |
| `data.error_code` | string | Error code when creation fails. Omitted otherwise. |
| `data.created_at` | string | Task creation time. |
| `data.updated_at` | string | Task update time. |

:::::
::::::
:::::::

## Error response

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "ErrParamInvalid",
  "msg": "Name cannot be empty",
  "data": null
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Human-readable error message. |
| `data` | null | `null` in an error response. |

:::::
::::::
:::::::

## Next steps

Use [List workspace-creation tasks](list-workspace-creations.md#request-example) to follow task status. After the status is `succeeded` and `workspace_id` appears, [list workspaces](list-workspaces.md#query-parameters) to confirm that the workspace is accessible.