## List the projects the caller sees (tenant:forge:read)

`GET /api/forge/v1/projects`

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

Requires `tenant:forge:read`. Private projects only for members and forge admins.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `state` | query | string |  | (one of `active`, `archived`) |

### Responses

- **200** Projects (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of ProjectView, required)
  - `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
{
  "items": [
    {
      "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": {
        "planningAgent": {
          "enabled": true,
          "language": "de"
        }
      },
      "spentMinutes": 14520,
      "state": "active",
      "updatedAt": "2026-11-11T14:20:00Z",
      "version": 7,
      "visibility": "tenant",
      "workCustomer": null
    },
    {
      "acceptsIntake": false,
      "access": {
        "canConfigure": true,
        "canCreateItem": true,
        "canDeleteItem": true,
        "canEditItem": true,
        "canManage": false,
        "canPlan": true,
        "canUseAgent": false,
        "member": true,
        "role": "maintainer"
      },
      "createdAt": "2026-10-05T08:30:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "defaultTypeId": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7b33",
      "description": "Mobile App für das Lager von Donau Maschinenbau in Neutraubling: Wareneingang, Umlagerung und Inventur mit Anbindung an das ERP.",
      "id": "7c2d4e6f-8a1b-4c3d-9e5f-6a7b8c9d0e1f",
      "key": "LAG",
      "name": "Lager-App Donau",
      "settings": {},
      "spentMinutes": 23880,
      "state": "active",
      "updatedAt": "2026-11-04T08:10:00Z",
      "version": 4,
      "visibility": "tenant",
      "workCustomer": {
        "customer": {
          "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
          "name": "Donau Maschinenbau AG"
        },
        "internal": false
      }
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/forge/v1/projects' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
