## Change a project (tenant:forge:write and project admin, or tenant:forge:admin)

`PATCH /api/forge/v1/projects/{key}`

Module: Forge · operationId: `patchForgeProject` · Tag: Projects · Auth: access token (`Authorization: Bearer <accessToken>`)

Requires `tenant:forge:admin`, or `tenant:forge:write` and project role admin. `version` is required; the key never changes. `workCustomer` (null clears it, absent keeps it) sets how work on the project and its items is booked in HR; a change affects only new work entries. Writes `forge.project.saved`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `key` | path | string | yes | Project key (e.g. APP) |

### Request body

`application/json` (required)

- `version` (integer, required): The version the change is based on
- `acceptsIntake` (boolean): Accept desk tickets from intake-only callers
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null clears it
- `description` (string): Description (Markdown) (max length 20000)
- `name` (string): Project name (max length 120)
- `visibility` (string): `private` or `tenant` (one of `private`, `tenant`)
- `workCustomer` (WorkCustomer | null): null clears it

Example:

```json
{
  "acceptsIntake": true,
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen und Rückfragen beantworten.",
  "version": 7
}
```

### Responses

- **200** Changed (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `acceptsIntake` (boolean, required): Callers with only `tenant:forge:intake` may hand desk tickets to the project
- `access` (Capabilities, required)
  - `canConfigure` (boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)
  - `canCreateItem` (boolean, required): Create items and comment
  - `canDeleteItem` (boolean, required): Delete items and anyone's comments
  - `canEditItem` (boolean, required): Edit items (status, fields, labels, assignees, sections, links)
  - `canManage` (boolean, required): Members, project settings, archive, delete
  - `canPlan` (boolean, required): Create, edit, close and reopen milestones; create, edit, start, close and delete iterations and put items into them (the rule of canEditItem)
  - `canUseAgent` (boolean, required): The planning agent may work on this item for the caller (canEditItem, the project enabled the agent, active project, not converted); always false on a project
  - `member` (boolean, required): The caller is a member of the project
  - `role` (string, required): Effective role; empty when none
- `createdAt` (string (date-time), required): When the project was created
- `createdBy` (string, required): E-mail of who created the project
- `description` (string, required): Markdown
- `id` (string (uuid), required): Project id
- `key` (string, required): Project key, prefix of item references (APP-12); never changes
- `name` (string, required): Project name
- `settings` (object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT route
- `state` (string, required): active or archived (archived: read-only) (one of `active`, `archived`)
- `updatedAt` (string (date-time), required): Last change
- `version` (integer, required): Optimistic-locking version; send it with PATCH
- `visibility` (string, required): `private`: members and tenant forge admins; `tenant`: every forge reader (one of `private`, `tenant`)
- `defaultTypeId` (string (uuid), nullable): Default item type of new items; null when none
- `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`forge:project:<id>`, worked minus breaks, ADR 0040); filled by the project read and list, null when HR does not answer (never an error)
- `workCustomer` (WorkCustomer | null): How work on the project and its items is booked in HR (ADR 0040); null = no setting (the person picks the customer)

Example 200 answer:

```json
{
  "acceptsIntake": true,
  "access": {
    "canConfigure": true,
    "canCreateItem": true,
    "canDeleteItem": true,
    "canEditItem": true,
    "canManage": false,
    "canPlan": true,
    "canUseAgent": false,
    "member": true,
    "role": "maintainer"
  },
  "createdAt": "2026-09-23T09:00:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b03",
  "description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
  "id": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "key": "APP",
  "name": "Kundenportal-App",
  "settings": {
    "handoff": {
      "originOnReturn": {
        "action": "none"
      },
      "receiverOnReturn": {
        "action": "close",
        "status": "erledigt"
      }
    },
    "planningAgent": {
      "enabled": true,
      "language": "de"
    }
  },
  "spentMinutes": 14520,
  "state": "active",
  "updatedAt": "2026-11-11T14:20:00Z",
  "version": 7,
  "visibility": "tenant",
  "workCustomer": null
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/projects/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"acceptsIntake":true,"description":"Die mobile App für Kunden von Muster IT: Tickets ansehen und Rückfragen beantworten.","version":7}'
```
