---
title: "Create a named persistent workspace"
method: POST
path: "/v1/workspaces"
tags: ["Workspaces"]
---

# Create a named persistent workspace

`POST /v1/workspaces`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/workspaces`
- Auth: HTTP bearer

Creates an empty tenant-owned workspace. A matching name and size replays the existing identity. Capacity and team count limits apply. Storage billing is disabled until an approved storage rate is configured.

## Request body

- WorkspaceCreateRequest
  - `name` string, required
  - `size_gb` number, required: Requested capacity in GiB within the configured team limit.

## Response `201`

Success

- WorkspaceRecord
  - `id` string, required
  - `name` string, required
  - `size_gb` number, required
  - `holder_id` string, nullable
  - `saved_at` string, date-time, nullable
  - `expired_at` string, date-time, nullable: Time the tenant retention policy expired saved workspace state. The namespace remains listed.
  - `cleanup_pending` boolean: Expired workspace objects still require cleanup. An empty namespace can be reused after cleanup settles.
  - `stored_bytes` integer, nullable
  - `last_error` string
  - `saving_for_termination` boolean
  - `billing_status` 'disabled_no_approved_storage_rate' | 'metered_subject_to_account_limits' | 'included_workspace_storage' | 'account_workspace_storage' | 'ephemeral_instance', required: Storage billing policy for this record. ephemeral_instance has no saved storage or storage charge. Its compute session is billed separately.

## Other responses

- `default`: Error. The code, message, and fix fields describe the rejection and its remedy.

## Changes

- **2026-10-01** `ba84c74aeec8`: 1 warning, 2 info
  - added the new `ephemeral_instance` enum value to the `billing_status` response property for the response status `201`
  - added the optional property `cleanup_pending` to the response with the `201` status
  - added the optional property `expired_at` to the response with the `201` status
- **2026-10-01** `544fef290a54`: 2 warning, 1 info
  - removed the optional property `cleanup_pending` from the response with the `201` status
  - removed the optional property `expired_at` from the response with the `201` status
  - removed the `ephemeral_instance` enum value from the `billing_status` response property for the response status `201`
- **2026-09-28** `5b5ed315c2a4`: 1 warning
  - added the new `ephemeral_instance` enum value to the `billing_status` response property for the response status `201`
- **2026-09-28** `12e777b060de`: 1 info
  - removed the `ephemeral_instance` enum value from the `billing_status` response property for the response status `201`
- **2026-09-27** `ed6520461760`: 1 warning
  - added the new `ephemeral_instance` enum value to the `billing_status` response property for the response status `201`

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/workspaces/post.md)

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)