---
title: "Create a workspace (tenant admins)"
method: POST
path: "/workspaces"
tags: ["Workspaces"]
---

# Create a workspace (tenant admins)

`POST /workspaces`

## Request body

- WorkspaceCreateRequest
  - `name` string, required
  - `netZero` 'on' | 'off' — Left out, off. on needs an eligible scope (409 NET_ZERO_INELIGIBLE).
  - `scope` WorkspaceScope — Every property left out is unrestricted; {} is all data. A present list is never empty.
    - `categories` string[]
    - `entityIds` string[]
    - `periodFrom` string, date
    - `periodTo` string, date
    - `scopes` integer[]
    - `siteIds` string[]

## Response `201`

Created workspace

- WorkspaceResponse
  - `data` Workspace, required
    - `archivedAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required
    - `createdBy` string, required
    - `id` string, required — ws_ + 32 hex; default for the default while it is virtual
    - `isDefault` boolean, required
    - `kind` 'default' | 'view' | 'department', required
    - `name` string, required
    - `netZero` 'on' | 'off', required — Net Zero is on in this workspace; always on in the default
    - `netZeroEligible` boolean, required — Net Zero may be turned on: the default, or a scope of whole entities with no categories or scopes
    - `role` 'viewer' | 'editor' | 'admin' | 'auditor' — the caller's effective role in it: the grant narrowed by the organization role
    - `scope` WorkspaceScope, required — Every property left out is unrestricted; {} is all data. A present list is never empty.
      - `categories` string[]
      - `entityIds` string[]
      - `periodFrom` string, date
      - `periodTo` string, date
      - `scopes` integer[]
      - `siteIds` string[]
    - `updatedAt` string, date-time, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — DUPLICATE_WORKSPACE_NAME; NET_ZERO_INELIGIBLE
- `422` — SCOPE_NOT_ASSIGNABLE: a site or entity is not an active one of this organization

## Changes

- **2026-10-03** `4189686230ca` — 1 breaking, 3 info
  - removed the required property `data/netZeroWritable` from the response with the `201` status
  - added the new optional request property `netZero`
  - added the required property `data/netZero` to the response with the `201` status
  - added the required property `data/netZeroEligible` to the response with the `201` status
- **2026-10-02** `766c2a40e369` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/workspaces/post.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/4189686230ca?raw)