## Save a view (tenant:forge:read for a personal view; a project view tenant:forge:write and maintainer, or tenant:forge:admin)

`POST /api/forge/v1/views`

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

Requires `tenant:forge:read` for a personal view (the default; needs the caller's e-mail address; optionally of a project the caller sees via `projectKey`). A project view (`scope` `project` with `projectKey`; without a project 400 `scope`) needs the right to configure the project (`tenant:forge:admin`, or `tenant:forge:write` and project role maintainer or higher; else 403) and an active project (409 `project_archived`) and writes `forge.config.updated`. `query` may only hold the item search filters (`q`, `status`, `category`, `type`, `label`, `assignee`, `milestone`, `iteration`, `open`) with the values the search accepts; anything else is 400 naming `query.<key>`.

### Request body

`application/json` (required)

- `columns` (array of string): Columns of the list
- `groupBy` (string, nullable): status, assignee, milestone, iteration or label-scope:<scope>; null clears it
- `kind` (string): list or board (one of `list`, `board`)
- `name` (string): Name (max length 80)
- `position` (integer): Order of the views
- `projectKey` (string): Create only: the project (required with scope project)
- `query` (object): Item search filters (see View.query); `open` may be a boolean
- `scope` (string): Create only: personal (default) or project (one of `personal`, `project`)
- `sort` (string): Sort order; empty = the default of the list (one of ``, `updated`, `created`, `rank`, `number`)
- `version` (integer): PATCH: the version the change is based on

Example:

```json
{
  "columns": [
    "ref",
    "title",
    "status",
    "assignees",
    "updatedAt"
  ],
  "kind": "list",
  "name": "Offene Android-Fehler",
  "projectKey": "APP",
  "query": {
    "label": "plattform::android",
    "open": true,
    "type": "fehler"
  },
  "scope": "personal",
  "sort": "updated"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `columns` (array of string, required): Columns of the list
- `createdAt` (string (date-time), required): When the view was created
- `groupBy` (string, nullable, required): status, assignee, milestone, iteration or label-scope:<scope>
- `id` (string (uuid), required): View id
- `kind` (string, required): list or board (one of `list`, `board`)
- `name` (string, required): Name (max length 80)
- `ownerRef` (string, required): E-mail address of the creator
- `position` (integer, required): Order of the views
- `projectId` (string (uuid), nullable, required): null: a tenant-wide items view (always personal)
- `projectKey` (string, nullable, required): Key of the project; null for a tenant-wide view
- `query` (object, required): Item search filters, as the query parameters of `GET /items` (strings)
  - `assignee` (string): Assignee e-mails, comma separated
  - `category` (string): Status categories, comma separated
  - `iteration` (string): Iteration ids, comma separated
  - `label` (string): Label names, comma separated
  - `milestone` (string): Milestone ids, comma separated
  - `open` (string): Only open (true) or only closed (false) items (one of `true`, `false`)
  - `q` (string): Full-text search or an item reference
  - `status` (string): Status keys, comma separated
  - `type` (string): Item type keys, comma separated
- `scope` (string, required): `personal`: the owner's own; `project`: part of the project's configuration (one of `personal`, `project`)
- `sort` (string, required): Empty: the default of the list the view runs in (one of ``, `updated`, `created`, `rank`, `number`)
- `version` (integer, required): Optimistic-locking version; send it with PATCH

Example 201 answer:

```json
{
  "columns": [],
  "createdAt": "2026-10-28T11:30:00Z",
  "groupBy": "status",
  "id": "2d3e4f5a-6b7c-4d8e-9fa0-1b2c3d4e5f01",
  "kind": "board",
  "name": "Aktuelle Iteration",
  "ownerRef": "emma.maier@muster-it.example",
  "position": 1,
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "projectKey": "APP",
  "query": {
    "iteration": "active"
  },
  "scope": "project",
  "sort": "rank",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/views' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"columns":["ref","title","status","assignees","updatedAt"],"kind":"list","name":"Offene Android-Fehler","projectKey":"APP","query":{"label":"plattform::android","open":true,"type":"fehler"},"scope":"personal","sort":"updated"}'
```
