Create a project from a template (tenant:forge:admin)
POST /api/forge/v1/projects
Module: Forge · operationId: createForgeProject · Tag: Projects · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:admin. Applies templateKey (built-in key or saved template id/key; default kanban) in the same transaction; the creator becomes member admin. Writes forge.project.saved.
Request body
application/json (required)
key(string, required): Project key, prefix of item references (APP-12); never changesname(string, required): Project name (max length 120)acceptsIntake(boolean): Callers with onlytenant:forge:intakemay hand desk tickets to the projectdescription(string): Description (Markdown) (max length 20000)templateKey(string): Built-in key or saved template id or key; default kanbanvisibility(string):private: members and tenant forge admins;tenant: every forge reader (one ofprivate,tenant; default"private")workCustomer(WorkCustomer): How work on a project and its items is booked in HR's Leistungserfassung (ADR 0040): eitherinternal: true(internal work, HR's internal kind) or acustomer– a masterdata address (id, at most 100 characters) with its name as a snapshot (at most 200 characters) – never both (400workCustomer).internalmay be left out and then isfalse, so{customer: {...}}alone is a customer project.customer(object): The masterdata address the work is booked forid(string, required): Masterdata address id (max length 100)name(string, required): Name of the address (snapshot) (max length 200)
internal(boolean): Internal work (not billed to a customer) (defaultfalse)
Example:
{
"acceptsIntake": true,
"description": "Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.",
"key": "APP",
"name": "Kundenportal-App",
"templateKey": "scrum",
"visibility": "tenant"
}
Responses
- 201 Created (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 409 Error (
application/json)
Fields of the 201 answer:
acceptsIntake(boolean, required): Callers with onlytenant:forge:intakemay hand desk tickets to the projectaccess(Capabilities, required)canConfigure(boolean, required): Change the project configuration (statuses, types, labels, fields, templates, repositories)canCreateItem(boolean, required): Create items and commentcanDeleteItem(boolean, required): Delete items and anyone's commentscanEditItem(boolean, required): Edit items (status, fields, labels, assignees, sections, links)canManage(boolean, required): Members, project settings, archive, deletecanPlan(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 projectmember(boolean, required): The caller is a member of the projectrole(string, required): Effective role; empty when none
createdAt(string (date-time), required): When the project was createdcreatedBy(string, required): E-mail of who created the projectdescription(string, required): Markdownid(string (uuid), required): Project idkey(string, required): Project key, prefix of item references (APP-12); never changesname(string, required): Project namesettings(object, required): Project settings (handoff, code intake, planning agent), each changed through its own PUT routestate(string, required): active or archived (archived: read-only) (one ofactive,archived)updatedAt(string (date-time), required): Last changeversion(integer, required): Optimistic-locking version; send it with PATCHvisibility(string, required):private: members and tenant forge admins;tenant: every forge reader (one ofprivate,tenant)defaultTypeId(string (uuid), nullable): Default item type of new items; null when nonespentMinutes(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 201 answer:
{
"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": {
"handoff": {
"originOnReturn": {
"action": "none"
},
"receiverOnReturn": {
"action": "close",
"status": "erledigt"
}
},
"planningAgent": {
"enabled": true,
"language": "de"
}
},
"spentMinutes": 14520,
"state": "active",
"updatedAt": "2026-11-11T14:20:00Z",
"version": 7,
"visibility": "tenant",
"workCustomer": null
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"acceptsIntake":true,"description":"Die mobile App für Kunden von Muster IT: Tickets ansehen, Rückfragen beantworten und Geräte-Inventar einsehen.","key":"APP","name":"Kundenportal-App","templateKey":"scrum","visibility":"tenant"}'