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 listgroupBy(string, nullable): status, assignee, milestone, iteration or label-scope:; null clears itkind(string): list or board (one oflist,board)name(string): Name (max length 80)position(integer): Order of the viewsprojectKey(string): Create only: the project (required with scope project)query(object): Item search filters (see View.query);openmay be a booleanscope(string): Create only: personal (default) or project (one ofpersonal,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:
{
"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 listcreatedAt(string (date-time), required): When the view was createdgroupBy(string, nullable, required): status, assignee, milestone, iteration or label-scope:id(string (uuid), required): View idkind(string, required): list or board (one oflist,board)name(string, required): Name (max length 80)ownerRef(string, required): E-mail address of the creatorposition(integer, required): Order of the viewsprojectId(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 viewquery(object, required): Item search filters, as the query parameters ofGET /items(strings)assignee(string): Assignee e-mails, comma separatedcategory(string): Status categories, comma separatediteration(string): Iteration ids, comma separatedlabel(string): Label names, comma separatedmilestone(string): Milestone ids, comma separatedopen(string): Only open (true) or only closed (false) items (one oftrue,false)q(string): Full-text search or an item referencestatus(string): Status keys, comma separatedtype(string): Item type keys, comma separated
scope(string, required):personal: the owner's own;project: part of the project's configuration (one ofpersonal,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:
{
"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 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"}'