## Create an item (desk:write)

`POST /api/desk/v1/items`

Module: Desk · operationId: `createItem` · Tag: Items · Auth: access token (`Authorization: Bearer <accessToken>`)

The body has the item's JSON shape. `spaceId` and `typeId` accept ids or keys; without
`typeId` the space's default type is used, without `status` the workflow's first "new" status.
Required fields of the type layout must be filled (`422 missing_fields`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string |  |  |

### Request body

`application/json` (required)

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item

Example:

```json
{
  "customFields": {
    "betroffenes_system": "FortiClient 7.2"
  },
  "customer": {
    "id": "K-10023",
    "name": "Muster GmbH"
  },
  "description": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "impact": "mittel",
  "spaceId": "SUP",
  "title": "VPN-Verbindung bricht ab",
  "typeId": "stoerung",
  "urgency": "hoch"
}
```

### Responses

- **200** Existing item (idempotency or dedupe key) (`application/json`)
- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 201 answer:

- `assignees` (array of object): People working on the item (the whole list)
  - `role` (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
  - `userRef` (string): Login (e-mail) of the person
- `categoryId` (string, nullable): Category of the item
- `confidential` (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
- `contact` (Ref | null): Masterdata contact person of the item (null clears)
- `customFields` (object): Merged; null removes a value
- `customer` (Ref | null): Masterdata customer of the item (null clears)
- `dedupeKey` (string): Create only; repeated deliveries return the existing item
- `description` (string): Markdown
- `dueAt` (string (date-time), nullable): Due date
- `dueHasTime` (boolean): dueAt carries a time of day (false: only the date counts)
- `estimateMinutes` (integer, nullable): Estimate in minutes
- `followUpAt` (string (date-time), nullable): When to follow up
- `impact` (string, nullable): Impact key of the priority matrix
- `kbWorthy` (boolean): Candidate for the knowledge base once resolved
- `labelIds` (array of string): Labels of the item (ids; the whole list)
- `parentId` (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
- `priority` (string, nullable): Priority key
- `projectId` (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
- `projectMilestoneId` (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
- `rank` (string): Board order (base-36 fraction)
- `source` (string): Create only; key of a source entry (bootstrap enums). API clients send `api`: the space's due date on receipt (`settings.dueOnReceipt`) tells the channels apart by it; without a source a ticket counts as manual.
- `sourceOrigin` (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (`comms:interaction:<id>` or `comms:calendar:<id>`; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
- `sourceRef` (string): Reference of the source (e.g. the sender address of a mail ticket)
- `spaceId` (string): Create only
- `startOn` (string (date), nullable): Start date
- `status` (string): Create only
- `summary` (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
- `teams` (array of object): Teams of the item (the whole list)
  - `role` (string): responsible or collaborating (one of `responsible`, `collaborating`)
  - `teamId` (string): Id of the team
- `title` (string): Title of the item (max length 500)
- `typeId` (string): Create only
- `urgency` (string, nullable): Urgency key of the priority matrix
- `weight` (integer, nullable): Weight of the item
- `checklistDone` (integer): Ticked checklist items
- `checklistTotal` (integer): Checklist items
- `childCount` (integer): Number of direct children
- `closedAt` (string (date-time), nullable): When the item reached a closed status
- `convertedTo` (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 `converted`; entries, participants and uploads by agents stay possible)
  - `at` (string (date-time)): When the ticket was converted
  - `id` (string): Id of the item the ticket became
  - `module` (string): Module of the item the ticket became (one of `desk`, `forge`)
  - `path` (string): Portal path of that item
  - `ref` (string): Reference of that item (#42 or APP-12)
- `convertingSince` (string (date-time)): A conversion is pending; edits are 409 `conversion_pending`
- `createdAt` (string (date-time)): When the item was created
- `createdBy` (string): Login (e-mail) of who created the item
- `forwarding` (boolean): A tombstone with requesters or people in copy: the forwarding stub
- `handoffs` (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: `GET /items/{ref}` and the answers of writes; omitted when there are none)
  - `attempts` (integer): Delivery attempts so far
  - `counterpartCheckedAt` (string (date-time)): When the other side was last synchronised
  - `counterpartContainerId` (string (uuid)): Space or project id of the other side
  - `counterpartContainerKey` (string): Space or project key of the other side
  - `counterpartItemId` (string (uuid)): Item id of the other side
  - `counterpartModule` (string): Module of the other side (one of `desk`, `forge`)
  - `counterpartRef` (string): Reference of the other side's item (e.g. #42 or APP-12)
  - `counterpartStage` (string): Last known stage of the other side's item (gone: deleted) (one of `new`, `active`, `waiting`, `done`, `cancelled`, `gone`)
  - `counterpartStatusKey` (string): Last known status key of the other side's item
  - `counterpartStatusName` (string): Last known status name of the other side's item
  - `createdAt` (string (date-time)): When the handoff was started
  - `createdByName` (string): Name of who started the handoff
  - `createdByRef` (string): Login (e-mail) of who started the handoff
  - `id` (string (uuid)): Id of the handoff
  - `itemId` (string (uuid)): Desk item of this side
  - `kind` (string): handoff (a new linked item) or conversion (the item moved) (one of `handoff`, `conversion`)
  - `lastError` (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
  - `nextAttemptAt` (string (date-time)): When delivery is tried next (pending)
  - `returnNote` (string): Note given when the item was handed back
  - `returnedAt` (string (date-time)): When the item was handed back
  - `returnedByName` (string): Name of who handed it back
  - `returnedByRef` (string): Login (e-mail) of who handed it back
  - `role` (string): origin: this ticket handed over; receiver: this ticket was received (one of `origin`, `receiver`)
  - `state` (string): State of the handoff (one of `open`, `handed_back`, `closed`, `converted`)
  - `syncState` (string): Delivery to the other module: pending, confirmed or failed (one of `pending`, `confirmed`, `failed`)
  - `updatedAt` (string (date-time)): When the handoff row last changed
  - `version` (integer): Version of the handoff row
- `id` (string): Id of the item
- `lastAgentPublicAt` (string (date-time), nullable): Last public
- `lastCustomerAt` (string (date-time), nullable): Last public
- `mergedIntoId` (string): Item this one was merged into (read-only afterwards)
- `number` (integer): Number of the item, unique in the tenant (#42)
- `pendingSuggestions` (integer): AI suggestions waiting for a person
- `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
- `projectTicketDisplay` (string, read-only): Ticket display of the item's project (`tickets`, `projects`, `hidden`); empty without project (one of ``, `tickets`, `projects`, `hidden`)
- `rating` (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
  - `comment` (string): Comment of the requester
  - `ratedAt` (string (date-time)): When the ticket was rated
  - `rating` (integer): Stars (1–5) (max 5)
  - `requesterEmail` (string): E-mail of the requester who rated
  - `requesterName` (string): Name of the requester who rated
- `slaDueAt` (string (date-time), nullable): Earliest running SLA deadline
- `slaState` (string): State of the item's SLA clocks (one of `none`, `running`, `warning`, `breached`, `paused`, `met`)
- `spentMinutes` (integer, nullable): Work HR booked on the ticket (subject `desk:item:<id>`, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
- `statusChangedAt` (string (date-time)): When the status last changed
- `summarySource` (string, read-only): Who wrote the summary last: `auto` (the first message), `ai` (an AI summary was applied) or `person` (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of `auto`, `ai`, `person`)
- `updatedAt` (string (date-time)): When the item was last changed
- `updatedBy` (string): Login (e-mail) of who last changed the item
- `version` (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "assignees": [],
  "createdAt": "2026-11-18T09:14:00Z",
  "createdBy": "api:ticket-import",
  "customFields": {
    "betroffenes_system": "FortiClient 7.2"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12",
    "name": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"
  },
  "description": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c4e",
  "impact": "mittel",
  "labelIds": [],
  "number": 78,
  "phase": "new",
  "priority": "hoch",
  "slaDueAt": "2026-11-18T13:14:00Z",
  "slaState": "running",
  "source": "api",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "status": "neu",
  "statusChangedAt": "2026-11-18T09:14:00Z",
  "summary": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "summarySource": "auto",
  "teams": [],
  "title": "VPN-Verbindung bricht ab",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-18T09:14:00Z",
  "updatedBy": "api:ticket-import",
  "urgency": "hoch",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customFields":{"betroffenes_system":"FortiClient 7.2"},"customer":{"id":"K-10023","name":"Muster GmbH"},"description":"Seit heute morgen trennt der VPN-Client alle 5 Minuten.","impact":"mittel","spaceId":"SUP","title":"VPN-Verbindung bricht ab","typeId":"stoerung","urgency":"hoch"}'
```
