# Update Workspace

`PATCH /api/v1/workspaces/{id}`

## Description
Update workspace metadata. **Admin permission required.** Fields not present are left unchanged. Slug is immutable — renaming only changes the display name.

## Parameters

- **id** (path) (required) — `string`: Workspace ID.

## Request Body

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "color": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$"
    },
    "billedAccountUserId": {
      "type": "string",
      "description": "New billed account user. Must already be an admin on the workspace."
    },
    "allowPersonalApiKeys": {
      "type": "boolean"
    }
  }
}
```

## Responses

### 200 — Workspace updated. The returned workspace carries role: "admin" instead of roleKey and roleKeys.

```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 or billed account is not a workspace admin.

### 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 — Admin permission required to update workspace.

### 404 — Workspace not found.
