Create a project; it gets the next project number (desk:write)
POST /api/desk/v1/projects
Module: Desk · operationId: createProject · Tag: Projects · Auth: access token (Authorization: Bearer <accessToken>)
spaceId (the home space, id or key) is required.
Request body
application/json (required)
spaceId(string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored spacetitle(string, required): Title of the project (max length 200)archived(boolean): Archived: the project is kept for existing data but no longer offered in pickersbudgetAmount(number, nullable): Budget as a net amount (EUR)budgetMinutes(integer, nullable): Time budget; the warning uses itbudgetState(string, read-only): Absent without a time budget or while the spent time is unknown (one ofok,warning,exceeded)createdAt(string (date-time), read-only): When the project was createdcreatedBy(string, read-only): Login (e-mail) of who created the projectcustomFields(object): Values of the type's layout fields, keyed by field key ("cf." optional on input)customer(Ref | null): Masterdata customer of the projectdescription(string): Description of the projectendOn(string (date), nullable): Planned endflatRateArticle(object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returnedhourlyRate(number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returnedid(string, read-only): Id of the projectitemsByPhase(object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)number(integer, read-only): Project number, unique in the tenantphase(string, read-only): Phase of the status (one ofnew,active,waiting,done)plannedMinutes(integer, nullable): Planned effort in minutesresponsibleName(string): Name of the person responsibleresponsibleRef(string): Login (e-mail) of the person responsiblespentMinutes(integer, nullable, read-only): Work HR booked with the project as reference (desk:project:<id>, worked minus breaks, ADR 0040); null when HR does not answerstartOn(string (date), nullable): Planned startstatus(string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelledticketDisplay(string): How the project's tickets show in the ticket lists and boards:ticketsas ordinary tickets,projectsonly on the projects page,hiddennot in the lists (unless assigned to the viewer). An update without it keeps the stored value (one oftickets,projects,hidden; default"tickets")typeId(string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fieldsupdatedAt(string (date-time), read-only): When the project was last changedupdatedBy(string, read-only): Login (e-mail) of who last changed the projectversion(integer): Version of the project; send it back on change (409 version_conflict when it is outdated)warnPercent(integer): Budget warning from this share (default 80) (max 100)
Example:
{
"budgetMinutes": 2400,
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12",
"name": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"
},
"endOn": "2026-12-19",
"responsibleRef": "marie.wagner@muster-it.example",
"spaceId": "PRJ",
"startOn": "2026-12-01",
"title": "Microsoft-365-Umstellung Kanzlei Hofmann",
"warnPercent": 80
}
Responses
- 201 Project (
application/json) - 422 Invalid field;
spaceIdis missing, not a space of the tenant, or archived
Fields of the 201 answer:
spaceId(string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored spacetitle(string, required): Title of the project (max length 200)archived(boolean): Archived: the project is kept for existing data but no longer offered in pickersbudgetAmount(number, nullable): Budget as a net amount (EUR)budgetMinutes(integer, nullable): Time budget; the warning uses itbudgetState(string, read-only): Absent without a time budget or while the spent time is unknown (one ofok,warning,exceeded)createdAt(string (date-time), read-only): When the project was createdcreatedBy(string, read-only): Login (e-mail) of who created the projectcustomFields(object): Values of the type's layout fields, keyed by field key ("cf." optional on input)customer(Ref | null): Masterdata customer of the projectdescription(string): Description of the projectendOn(string (date), nullable): Planned endflatRateArticle(object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returnedhourlyRate(number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returnedid(string, read-only): Id of the projectitemsByPhase(object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)number(integer, read-only): Project number, unique in the tenantphase(string, read-only): Phase of the status (one ofnew,active,waiting,done)plannedMinutes(integer, nullable): Planned effort in minutesresponsibleName(string): Name of the person responsibleresponsibleRef(string): Login (e-mail) of the person responsiblespentMinutes(integer, nullable, read-only): Work HR booked with the project as reference (desk:project:<id>, worked minus breaks, ADR 0040); null when HR does not answerstartOn(string (date), nullable): Planned startstatus(string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelledticketDisplay(string): How the project's tickets show in the ticket lists and boards:ticketsas ordinary tickets,projectsonly on the projects page,hiddennot in the lists (unless assigned to the viewer). An update without it keeps the stored value (one oftickets,projects,hidden; default"tickets")typeId(string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fieldsupdatedAt(string (date-time), read-only): When the project was last changedupdatedBy(string, read-only): Login (e-mail) of who last changed the projectversion(integer): Version of the project; send it back on change (409 version_conflict when it is outdated)warnPercent(integer): Budget warning from this share (default 80) (max 100)
Example 201 answer:
{
"archived": false,
"budgetAmount": 22400,
"budgetMinutes": 9600,
"budgetState": "ok",
"createdAt": "2026-11-02T07:30:00Z",
"createdBy": "emma.maier@muster-it.example",
"customFields": {
"ansprechpartner_kunde": "Stefan Eder (IT-Leiter)",
"auftragsnummer": "A-2026-0412"
},
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
"name": "Donau Maschinenbau AG"
},
"description": "Einführung der ERP-Lösung bei Donau Maschinenbau am Standort Neutraubling: Installation, Konfiguration, Datenübernahme, Schulung und Produktivstart.",
"endOn": "2026-11-23",
"id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"itemsByPhase": {
"active": 3,
"done": 9,
"new": 9,
"waiting": 0
},
"number": 1,
"phase": "active",
"plannedMinutes": 8400,
"responsibleName": "Emma Maier",
"responsibleRef": "emma.maier@muster-it.example",
"spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
"spentMinutes": 4260,
"startOn": "2026-11-02",
"status": "laufend",
"ticketDisplay": "tickets",
"title": "ERP-Einführung Donau Maschinenbau",
"typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
"updatedAt": "2026-11-12T16:00:00Z",
"updatedBy": "emma.maier@muster-it.example",
"version": 6,
"warnPercent": 80
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"budgetMinutes":2400,"customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12","name":"Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"},"endOn":"2026-12-19","responsibleRef":"marie.wagner@muster-it.example","spaceId":"PRJ","startOn":"2026-12-01","title":"Microsoft-365-Umstellung Kanzlei Hofmann","warnPercent":80}'