ConnectCloud Developers

Change a saved view (its owner for a personal view; a project view tenant:forge:write and maintainer, or tenant:forge:admin)

PATCH /api/forge/v1/views/{id}

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

Personal views are changed by their owner (anyone else 404), project views by those who configure the project (403 for others who see it; a view of a project the caller cannot see is 404). version is required (409 version_conflict); scope and project never change. Same validation as creating. Nothing changed writes no event and keeps the version. A project view writes forge.config.updated.

Parameters

Name In Type Required Description
id path string (uuid) yes

Request body

application/json (required)

  • columns (array of string): Columns of the list
  • groupBy (string, nullable): status, assignee, milestone, iteration or label-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:

{
  "groupBy": "assignee",
  "name": "Iteration nach Zuständigen",
  "version": 1
}

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:

  • 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:
  • 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 200 answer:

{
  "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

curl -X PATCH 'https://api.mbcom.cloud/api/forge/v1/views/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"groupBy":"assignee","name":"Iteration nach Zuständigen","version":1}'

View as Markdown · Interactive reference · OpenAPI