---
title: "Create a workspace"
method: POST
path: "/api/v1/public/workspaces"
tags: ["Account"]
---

# Create a workspace

`POST /api/v1/public/workspaces`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/workspaces`
- Auth: HTTP bearer

Create a workspace administered by the authenticated user.

Idempotent: re-creating a workspace the user already administers under the
same name returns that workspace with ``created: false``.

Args:
    request (Request): Incoming request (rate-limit plumbing).
    response (Response): Outgoing response (rate-limit plumbing).
    auth (AccountStampedAuth): Account-scope user auth (session token or
        CLI access JWT); its resolved ``user_id`` becomes the actor.
    payload (CreateWorkspaceRequest): The workspace to create.
    _live (None): Write-path liveness gate (blocks a revoked JWT session).

Returns:
    CreateWorkspaceResponse: The created (or matched) workspace.

## Request body

- CreateWorkspaceRequest: Body for creating a workspace the caller will administer.
  - `name` string, required

## Response `200`

Successful Response

- CreateWorkspaceResponse: The created (or idempotently matched) workspace.
  - `created` boolean, required
  - `id` string, required
  - `name` string, required
  - `role` string, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed or session revoked
- `403`: Insufficient role or wrong credential kind
- `404`: Not found
- `409`: Name already used by a workspace the user no longer administers
- `422`: Validation Error
- `503`: Write service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)