Create a workspace

OpenAPI contract

Method

POST

Path

/api/v1/workspaces

Security

jwtBearer (bearer)

Response status

201 400 401 403 404 409 429 500

Request and response schemas

JSON

{
  "requestBody": {
    "application/json": {
      "$ref": "#/components/schemas/CreateWorkspaceRequest"
    }
  },
  "responses": {
    "201": {
      "description": "Workspace created",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/WorkspaceResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "401": {
      "description": "Authentication required or invalid",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "403": {
      "description": "Authenticated but not permitted",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "404": {
      "description": "Requested workspace resource was not found",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "409": {
      "description": "Request conflicts with current workspace state",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

POST /api/v1/workspaces is JWT-only and requires organization-management permission. Send a nonblank name of at most 100 characters and an optional organizationId. Without organizationId, the service uses the caller's personal organization. Names are trimmed and must be unique within the organization, ignoring case.

The creator receives an active ADMIN workspace membership. A duplicate name returns a conflict, and an organization the caller cannot manage is not exposed. An nfy_ automation key cannot create a workspace.

json

{"name":"Release engineering","organizationId":"00000000-0000-0000-0000-000000000000"}