Add a template's missing configuration to a project (tenant:forge:write and maintainer, or tenant:forge:admin)
POST /api/forge/v1/projects/{key}/apply-template
Module: Forge · operationId: applyForgeProjectTemplate · Tag: Templates · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:admin, or tenant:forge:write and project role maintainer or admin. Adds what the project lacks (matched by key, labels by name); never changes or deletes existing rows. dryRun=true answers the plan without writing. Writes forge.config.updated.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
dryRun |
query | boolean | (default false) |
|
key |
path | string | yes | Project key (e.g. APP) |
Request body
application/json (required)
templateKey(string, required): Built-in key or saved template id or key
Example:
{
"templateKey": "scrum"
}
Responses
- 200 What was (or would be) added and skipped (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 404 Error (
application/json) - 409 Error (
application/json)
Fields of the 200 answer:
customFields(array of CustomField, required): Custom fields in position orderid(string (uuid), required): Field idkey(string, required): Field key: the key incustomFieldsof an item; never changeskind(string, required): Value type; never changes (one oftext,longtext,number,date,datetime,bool,select,multiselect,user,url)label(string, required): Display labeloptions(array of FieldOption, required): Choices of select and multiselect fieldsposition(integer, required): Order in the configurationrequired(boolean, required): Items of the types the field applies to need a valuetypeKeys(array of string, required): Item type keys; empty = every typeversion(integer, required): Optimistic-locking version; send it with PATCH
itemTemplates(array of ItemTemplate, required): Item templates in position orderbody(string, required): Markdownid(string (uuid), required): Template idkey(string, required): Template key (templateKeyof a new item)labelIds(array of string (uuid), required): Labels it setsname(string, required): Display nameposition(integer, required): Order in the configurationtitle(string, required): Title it prefillsversion(integer, required): Optimistic-locking version; send it with PATCHtypeId(string (uuid), nullable): Item type it sets; null = none
itemTypes(array of ItemType, required): Item types in position orderarchived(boolean, required): Archived: no new items of the typeicon(string, required): Icon name shown in the portalid(string (uuid), required): Item type idkey(string, required): Type key; never changeslevel(integer, required): 0 = leaf; a parent type has a higher level (max 5)name(string, required): Display nameposition(integer, required): Order in the configurationversion(integer, required): Optimistic-locking version; send it with PATCHworkflowId(string (uuid), required): Workflow the items of the type follow
labels(array of Label, required): Labels sorted by namecolor(string, required): Color token (neutral, primary, …) or #rrggbbdescription(string, required): Descriptionid(string (uuid), required): Label idname(string, required): scope::value makes it exclusive within the scopeversion(integer, required): Optimistic-locking version; send it with PATCH
ownerships(array of Ownership, required): Ownerships (code ownership) in position orderdeputyRefs(array of string, required): E-mails of the deputies (members, at least developer); need an owner of their owndescription(string, required): Description (max length 2000)id(string (uuid), required): Ownership iditemTypes(array of string, required): Item type keys: items of these types belong here (without an owner:: label)key(string, required): Key; never changes (its label isowner::<key>)labelId(string (uuid), required): The ownership's labelowner::<key>; items carry it and it wins over the matchersmatchLabelIds(array of string (uuid), required): Plain labels (neverowner::…): items carrying one belong here (without an owner:: label); the later position winsname(string, required): Display name (max length 80)ownerRef(string, nullable, required): E-mail of the owner person (a member, at least developer); exclusive with ownerTeamIdownerTeamId(string (uuid), nullable, required): The owning team; exclusive with ownerRef. Neither is allowed only with a parent (inherited)parentId(string (uuid), nullable, required): The parent ownership (same project, no cycle, at most 4 levels); without an owner of its own the nearest ancestor's appliespaths(array of string, required): Repository path patterns, the CODEOWNERS subset: segments separated by/,*and?within a segment,**as a whole segment for any number of directories. A pattern without/(other than a trailing one) matches at any depth, one with/is relative to the root (a leading/anchors explicitly); a trailing/matches directories. A pattern whose last segment has no wildcard also matches everything below the directory it names (hr,/apps/github); one ending in a wildcard matches only what it names (docs/*). No character classes,\,!,#or spaces. Paths decide only for code (CODEOWNERS, scm).position(integer, required): Precedence: a later ownership wins a path or an item both matchversion(integer, required): Optimistic-locking version; send it with PATCH
sectionDefs(array of SectionDef, required): Section definitions in position orderid(string (uuid), required): Section definition idkey(string, required): Section key; never changeskind(string, required): markdown or checklist (one ofmarkdown,checklist)label(string, required): Display labelplacement(string, required): Where the portal shows it: a tab or the side column (one oftab,aside)position(integer, required): Order in the configurationtypeKeys(array of string, required): Item type keys the section applies to; empty = every typeversion(integer, required): Optimistic-locking version; send it with PATCH
statuses(array of Status, required): Statuses in position ordercategory(string, required): Status category (the group the status belongs to) (one oftriage,todo,active,on_hold,done,cancelled)color(string, required): Color token (neutral, primary, …) or #rrggbbid(string (uuid), required): Status idisDefault(boolean, required): Where new items start; exactly one, in triage or todokey(string, required): Status key; never changesname(string, required): Display nameposition(integer, required): Order in the configurationversion(integer, required): Optimistic-locking version; send it with PATCH
teams(array of Team, required): Teams in position orderdescription(string, required): Description (max length 2000)id(string (uuid), required): Team idkey(string, required): Team key; never changesmemberRefs(array of string, required): E-mails, the first is the leadname(string, required): Display name (max length 80)position(integer, required): Order in the configurationversion(integer, required): Optimistic-locking version; send it with PATCH
workflows(array of Workflow, required): Workflows in position orderid(string (uuid), required): Workflow idkey(string, required): Workflow key; never changesname(string, required): Display nameposition(integer, required): Order in the configurationstatusIds(array of string (uuid), required): Statuses of the workflowtransitions(array of Transition, required): Empty = free movement among the statusesversion(integer, required): Optimistic-locking version; send it with PATCH
added(object, required): Keys added, per collectionskipped(object, required): Keys skipped because the project has them already, per collectiondefaultTypeId(string (uuid)): The default item type the template set (only when the project had none)
Example 200 answer:
{
"added": {
"customFields": [
"story_points"
],
"itemTypes": [
"subtask"
],
"labels": [
"sprint-ziel"
]
},
"customFields": [
{
"id": "9b5c6d7e-8f9a-4b0c-9dbe-5f6a7b8c9d11",
"key": "story_points",
"kind": "number",
"label": "Story Points",
"options": [],
"position": 0,
"required": false,
"typeKeys": [
"story",
"aufgabe",
"fehler"
],
"version": 1
}
],
"itemTemplates": [],
"itemTypes": [
{
"archived": false,
"icon": "i-lucide-list-checks",
"id": "7f3a4b5c-6d7e-4f8a-9b9c-3d4e5f6a7c15",
"key": "subtask",
"level": 0,
"name": "Sub-Task",
"position": 4,
"version": 1,
"workflowId": "6e2f3a4b-5c6d-4e7f-9a8b-2c3d4e5f6a11"
}
],
"labels": [
{
"color": "primary",
"description": "Trägt zum Sprint-Ziel bei",
"id": "8a4b5c6d-7e8f-4a9b-8cad-4e5f6a7b8d17",
"name": "sprint-ziel",
"version": 1
}
],
"ownerships": [],
"sectionDefs": [],
"skipped": {
"automations": [
"unteraufgaben-erledigt",
"pr-gemergt-erledigt"
],
"itemTemplates": [
"fehlerbericht"
],
"itemTypes": [
"epic",
"story",
"aufgabe",
"fehler"
],
"labels": [
"priority::hoch",
"priority::mittel",
"priority::niedrig",
"bug",
"docs"
],
"sectionDefs": [
"plan",
"agent_notes",
"acceptance"
],
"statuses": [
"triage",
"offen",
"in_arbeit",
"review",
"erledigt",
"verworfen"
],
"workflows": [
"standard"
]
},
"statuses": [],
"teams": [],
"workflows": []
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/apply-template' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"templateKey":"scrum"}'