# workspace_save

Create, Update or Archive Workspace

## Beschreibung

Admins and employers can manage workspaces in their account. Omit id
to create (name and key required); pass a wsp_… ID to update only the
supplied fields. The creator becomes a workspace manager. Keys are
normalized to uppercase and cannot change once the workspace has tasks.
Set archived: true to archive or false to restore an existing workspace.
Archiving preserves its contents; General cannot be archived.
Use workspace_list(management: true, include_archived: true) to read
settings and discover all workspaces you can administer.
Workspace-scoped agents can only update already granted workspaces;
a workspace tool grant cannot authorize creating a new workspace.

## Zugriff

Zugriffsprofil: `gated`. Module: `none`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja | Account prefix ID (acct_…). |
| `id` | string | Nein | Workspace prefix ID (wsp_…). Omit to create. |
| `archived` | boolean | Nein | Existing workspaces only: true archives, false restores. |
| `name` | string | Nein | Required on create; at most 80 characters. |
| `key` | string | Nein | Required on create; 2–4 letters/digits. Editable only before any tasks exist. |
| `color` | string | Nein |  |
| `description` | string / null | Nein | Plain text. Null or an empty string clears it. |
| `icon_emoji` | string / null | Nein | Unicode emoji. Null or an empty string clears it. |
| `tasks_enabled` | boolean | Nein |  |
| `subtasks_enabled` | boolean | Nein |  |
| `recurring_tasks_enabled` | boolean | Nein |  |
| `projects_enabled` | boolean | Nein | Requires tasks_enabled. |
| `roadmaps_enabled` | boolean | Nein | Requires projects_enabled. |
| `estimates_enabled` | boolean | Nein |  |
| `estimate_scale` | string | Nein |  |
| `cycles_enabled` | boolean | Nein | Disabling archives upcoming cycles; active cycles remain. |
| `cycle_duration_weeks` | integer / null | Nein | 1–4 weeks; null selects cycle_custom_days. |
| `cycle_custom_days` | integer / null | Nein | 1–365 days when cycle_duration_weeks is null. |
| `cooldown_duration_weeks` | integer | Nein |  |
| `cycle_start_day` | integer | Nein | 0 = Sunday through 6 = Saturday. |
| `auto_create_count` | integer | Nein |  |
| `carry_over_mode` | string | Nein |  |
| `carry_over_statuses` | array | Nein | Task status symbolic keys; only valid with carry_over_mode: by_status. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (acct_…)."
    },
    "id": {
      "type": "string",
      "description": "Workspace prefix ID (wsp_…). Omit to create."
    },
    "archived": {
      "type": "boolean",
      "description": "Existing workspaces only: true archives, false restores."
    },
    "name": {
      "type": "string",
      "description": "Required on create; at most 80 characters."
    },
    "key": {
      "type": "string",
      "description": "Required on create; 2–4 letters/digits. Editable only before any tasks exist."
    },
    "color": {
      "type": "string",
      "enum": [
        "emerald",
        "violet",
        "amber",
        "rose",
        "sky",
        "indigo",
        "slate",
        "gray"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Plain text. Null or an empty string clears it."
    },
    "icon_emoji": {
      "type": [
        "string",
        "null"
      ],
      "description": "Unicode emoji. Null or an empty string clears it."
    },
    "tasks_enabled": {
      "type": "boolean"
    },
    "subtasks_enabled": {
      "type": "boolean"
    },
    "recurring_tasks_enabled": {
      "type": "boolean"
    },
    "projects_enabled": {
      "type": "boolean",
      "description": "Requires tasks_enabled."
    },
    "roadmaps_enabled": {
      "type": "boolean",
      "description": "Requires projects_enabled."
    },
    "estimates_enabled": {
      "type": "boolean"
    },
    "estimate_scale": {
      "type": "string",
      "enum": [
        "fibonacci",
        "linear",
        "powers_of_two"
      ]
    },
    "cycles_enabled": {
      "type": "boolean",
      "description": "Disabling archives upcoming cycles; active cycles remain."
    },
    "cycle_duration_weeks": {
      "type": [
        "integer",
        "null"
      ],
      "description": "1–4 weeks; null selects cycle_custom_days."
    },
    "cycle_custom_days": {
      "type": [
        "integer",
        "null"
      ],
      "description": "1–365 days when cycle_duration_weeks is null."
    },
    "cooldown_duration_weeks": {
      "type": "integer"
    },
    "cycle_start_day": {
      "type": "integer",
      "description": "0 = Sunday through 6 = Saturday."
    },
    "auto_create_count": {
      "type": "integer"
    },
    "carry_over_mode": {
      "type": "string",
      "enum": [
        "off",
        "all",
        "by_status"
      ]
    },
    "carry_over_statuses": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Task status symbolic keys; only valid with carry_over_mode: by_status."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "workspace": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "key": {
          "type": "string"
        },
        "color": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "icon_emoji": {
          "type": [
            "string",
            "null"
          ]
        },
        "archived": {
          "type": "boolean"
        },
        "general": {
          "type": "boolean"
        },
        "key_editable": {
          "type": "boolean"
        },
        "tasks_enabled": {
          "type": "boolean"
        },
        "subtasks_enabled": {
          "type": "boolean"
        },
        "recurring_tasks_enabled": {
          "type": "boolean"
        },
        "projects_enabled": {
          "type": "boolean"
        },
        "roadmaps_enabled": {
          "type": "boolean"
        },
        "estimates_enabled": {
          "type": "boolean"
        },
        "estimate_scale": {
          "type": "string"
        },
        "role": {
          "type": [
            "string",
            "null"
          ],
          "description": "manager / member / null when caller is not on the workspace."
        },
        "cycles": {
          "type": "object",
          "description": "Per-workspace cycles config (ENG-1089). Most workspaces keep defaults; only meaningful once `enabled` is true.",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "duration_weeks": {
              "type": [
                "integer",
                "null"
              ],
              "description": "1-4 weeks, or null when running on custom_days."
            },
            "custom_days": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Cycle length in days when duration_weeks is null."
            },
            "duration_days": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Collapsed day count — duration_weeks * 7 or custom_days, whichever is set."
            },
            "cooldown_weeks": {
              "type": "integer",
              "description": "Gap between consecutive cycles, in weeks."
            },
            "start_day": {
              "type": "integer",
              "description": "Date#wday-style: 0 = Sunday, 1 = Monday, …, 6 = Saturday."
            },
            "auto_create_count": {
              "type": "integer",
              "description": "How many upcoming cycles the lifecycle scheduler keeps ahead."
            },
            "estimates_required": {
              "type": "boolean",
              "description": "When true, tasks must carry an estimate before they can be added to a cycle (gates velocity metrics)."
            },
            "carry_over_mode": {
              "type": "string"
            },
            "carry_over_statuses": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "enabled",
            "cooldown_weeks",
            "start_day",
            "auto_create_count",
            "estimates_required"
          ]
        }
      },
      "required": [
        "id",
        "name",
        "key",
        "color",
        "cycles",
        "archived",
        "general",
        "key_editable"
      ]
    }
  },
  "required": [
    "workspace"
  ],
  "type": "object"
}
```