# Create Workspace

`POST /api/v1/workspaces`

## Description
Create a new workspace under the API key holder's organization. Only unscoped personal API keys can create workspaces. Workspace-scoped, scoped, and organization keys receive HTTP 403. A default agent workflow is created unless skipDefaultWorkflow is true.

## Request Body

```json
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Workspace display name."
    },
    "color": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$",
      "description": "Optional hex color (#rrggbb). Defaults to a random color."
    },
    "skipDefaultWorkflow": {
      "type": "boolean",
      "default": false,
      "description": "When true, do NOT create the default agent workflow."
    }
  }
}
```

## Responses

### 200 — Workspace created.

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "workspace": {
          "type": "object",
          "description": "A workspace groups workflows, tables, knowledge bases, files, and credentials under a single billing + permission boundary.",
          "properties": {
            "id": {
              "type": "string",
              "description": "Unique workspace identifier.",
              "example": "wsp_abc123"
            },
            "name": {
              "type": "string",
              "description": "Workspace display name.",
              "example": "Engineering"
            },
            "slug": {
              "type": "string",
              "description": "Immutable URL slug assigned at creation. Crockford base32, unique within the parent organization.",
              "example": "engin3r2"
            },
            "color": {
              "type": "string",
              "description": "Hex color shown in the workspace switcher.",
              "pattern": "^#[0-9a-fA-F]{6}$",
              "example": "#3972F6"
            },
            "ownerId": {
              "type": "string",
              "description": "User ID of the workspace owner."
            },
            "organizationId": {
              "type": "string",
              "description": "Parent organization ID."
            },
            "billedAccountUserId": {
              "type": "string",
              "description": "User ID whose subscription is billed for this workspace's usage. Defaults to ownerId."
            },
            "allowPersonalApiKeys": {
              "type": "boolean",
              "description": "Whether members can create personal API keys for this workspace.",
              "default": true
            },
            "roleKey": {
              "type": [
                "string",
                "null"
              ],
              "description": "The caller's most significant role key on this workspace. Seeded keys are workspace:admin, workspace:write, and workspace:read. Custom role keys can also appear.",
              "example": "workspace:admin"
            },
            "roleKeys": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Every role key the caller holds on this workspace, including organization-wide roles.",
              "example": [
                "workspace:admin"
              ]
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            },
            "updatedAt": {
              "type": "string",
              "format": "date-time"
            },
            "archivedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "Set when the workspace is archived; null otherwise."
            }
          }
        }
      }
    }
  }
}
```

### 400 — Invalid request body (zod field errors in `details.fieldErrors`).

### 401 — Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 403 — Workspace-scoped, scoped, and organization API keys cannot create workspaces. Use an unscoped personal API key.
