Change the status along the workflow (desk:write)
POST /api/desk/v1/items/{ref}/transition
Module: Desk · operationId: transitionItem · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
version is the version the caller read: a ticket that changed since is 409 version_conflict. It is required unless the caller is an automation (a flow or a desk automation); a missing version is 400 invalid (field: version) – people, API keys, OAuth clients and the assistant always send it. An automation that sends none moves the ticket as it is; one that sends a version is checked like everyone else.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ref |
path | string | yes | Item id or number |
Request body
application/json (required)
status(string, required): Target status keycomment(string): Comment written with the changecommentVisibility(string): Visibility of the comment (default internal) (one ofinternal,public)fields(ItemInput)assignees(array of object): People working on the item (the whole list)role(string): Key of an assigneeRole entry (bootstrap enums); omitted = the default roleuserRef(string): Login (e-mail) of the person
categoryId(string, nullable): Category of the itemconfidential(boolean): Only holders of desk:confidential, the item's creator and its assignees see itcontact(Ref | null): Masterdata contact person of the item (null clears)customFields(object): Merged; null removes a valuecustomer(Ref | null): Masterdata customer of the item (null clears)dedupeKey(string): Create only; repeated deliveries return the existing itemdescription(string): MarkdowndueAt(string (date-time), nullable): Due datedueHasTime(boolean): dueAt carries a time of day (false: only the date counts)estimateMinutes(integer, nullable): Estimate in minutesfollowUpAt(string (date-time), nullable): When to follow upimpact(string, nullable): Impact key of the priority matrixkbWorthy(boolean): Candidate for the knowledge base once resolvedlabelIds(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 itpriority(string, nullable): Priority keyprojectId(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 descendantsprojectMilestoneId(string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the projectrank(string): Board order (base-36 fraction)source(string): Create only; key of a source entry (bootstrap enums). API clients sendapi: 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>orcomms:calendar:<id>; 400 otherwise); a free reference the portal links to /activities, never changed afterwardssourceRef(string): Reference of the source (e.g. the sender address of a mail ticket)spaceId(string): Create onlystartOn(string (date), nullable): Start datestatus(string): Create onlysummary(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 ofresponsible,collaborating)teamId(string): Id of the team
title(string): Title of the item (max length 500)typeId(string): Create onlyurgency(string, nullable): Urgency key of the priority matrixweight(integer, nullable): Weight of the item
version(integer): The version the caller read (a ticket changed since is 409version_conflict); required unless the caller is an automation (a flow or a desk automation); a missing version is 400invalid.
Example:
{
"comment": "Können Sie bitte kurz prüfen, ob die Gäste in den Zimmern 201 bis 212 wieder stabil verbunden sind?",
"commentVisibility": "public",
"status": "wartet_kunde",
"version": 6
}
Responses
- 200 Updated (
application/json) - 400
invalidwithfield: version: the caller is not an automation and sent no version (also: nostatus, an invalid body) (application/json) - 409 Error (
application/json) - 422 transition_denied, same_status, comment_required or missing_fields (
application/json)
Fields of the 200 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 roleuserRef(string): Login (e-mail) of the person
categoryId(string, nullable): Category of the itemconfidential(boolean): Only holders of desk:confidential, the item's creator and its assignees see itcontact(Ref | null): Masterdata contact person of the item (null clears)customFields(object): Merged; null removes a valuecustomer(Ref | null): Masterdata customer of the item (null clears)dedupeKey(string): Create only; repeated deliveries return the existing itemdescription(string): MarkdowndueAt(string (date-time), nullable): Due datedueHasTime(boolean): dueAt carries a time of day (false: only the date counts)estimateMinutes(integer, nullable): Estimate in minutesfollowUpAt(string (date-time), nullable): When to follow upimpact(string, nullable): Impact key of the priority matrixkbWorthy(boolean): Candidate for the knowledge base once resolvedlabelIds(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 itpriority(string, nullable): Priority keyprojectId(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 descendantsprojectMilestoneId(string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the projectrank(string): Board order (base-36 fraction)source(string): Create only; key of a source entry (bootstrap enums). API clients sendapi: 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>orcomms:calendar:<id>; 400 otherwise); a free reference the portal links to /activities, never changed afterwardssourceRef(string): Reference of the source (e.g. the sender address of a mail ticket)spaceId(string): Create onlystartOn(string (date), nullable): Start datestatus(string): Create onlysummary(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 ofresponsible,collaborating)teamId(string): Id of the team
title(string): Title of the item (max length 500)typeId(string): Create onlyurgency(string, nullable): Urgency key of the priority matrixweight(integer, nullable): Weight of the itemchecklistDone(integer): Ticked checklist itemschecklistTotal(integer): Checklist itemschildCount(integer): Number of direct childrenclosedAt(string (date-time), nullable): When the item reached a closed statusconvertedTo(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 409converted; entries, participants and uploads by agents stay possible)at(string (date-time)): When the ticket was convertedid(string): Id of the item the ticket becamemodule(string): Module of the item the ticket became (one ofdesk,forge)path(string): Portal path of that itemref(string): Reference of that item (#42 or APP-12)
convertingSince(string (date-time)): A conversion is pending; edits are 409conversion_pendingcreatedAt(string (date-time)): When the item was createdcreatedBy(string): Login (e-mail) of who created the itemforwarding(boolean): A tombstone with requesters or people in copy: the forwarding stubhandoffs(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 farcounterpartCheckedAt(string (date-time)): When the other side was last synchronisedcounterpartContainerId(string (uuid)): Space or project id of the other sidecounterpartContainerKey(string): Space or project key of the other sidecounterpartItemId(string (uuid)): Item id of the other sidecounterpartModule(string): Module of the other side (one ofdesk,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 ofnew,active,waiting,done,cancelled,gone)counterpartStatusKey(string): Last known status key of the other side's itemcounterpartStatusName(string): Last known status name of the other side's itemcreatedAt(string (date-time)): When the handoff was startedcreatedByName(string): Name of who started the handoffcreatedByRef(string): Login (e-mail) of who started the handoffid(string (uuid)): Id of the handoffitemId(string (uuid)): Desk item of this sidekind(string): handoff (a new linked item) or conversion (the item moved) (one ofhandoff,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 loggednextAttemptAt(string (date-time)): When delivery is tried next (pending)returnNote(string): Note given when the item was handed backreturnedAt(string (date-time)): When the item was handed backreturnedByName(string): Name of who handed it backreturnedByRef(string): Login (e-mail) of who handed it backrole(string): origin: this ticket handed over; receiver: this ticket was received (one oforigin,receiver)state(string): State of the handoff (one ofopen,handed_back,closed,converted)syncState(string): Delivery to the other module: pending, confirmed or failed (one ofpending,confirmed,failed)updatedAt(string (date-time)): When the handoff row last changedversion(integer): Version of the handoff row
id(string): Id of the itemlastAgentPublicAt(string (date-time), nullable): Last publiclastCustomerAt(string (date-time), nullable): Last publicmergedIntoId(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 personphase(Phase): (one ofnew,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 requesterratedAt(string (date-time)): When the ticket was ratedrating(integer): Stars (1–5) (max 5)requesterEmail(string): E-mail of the requester who ratedrequesterName(string): Name of the requester who rated
slaDueAt(string (date-time), nullable): Earliest running SLA deadlineslaState(string): State of the item's SLA clocks (one ofnone,running,warning,breached,paused,met)spentMinutes(integer, nullable): Work HR booked on the ticket (subjectdesk:item:<id>, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answerstatusChangedAt(string (date-time)): When the status last changedsummarySource(string, read-only): Who wrote the summary last:auto(the first message),ai(an AI summary was applied) orperson(edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one ofauto,ai,person)updatedAt(string (date-time)): When the item was last changedupdatedBy(string): Login (e-mail) of who last changed the itemversion(integer): Version of the item; send it back on change (409 version_conflict when it is outdated)
Example 200 answer:
{
"assignees": [
{
"role": "owner",
"userRef": "lukas.wimmer@muster-it.example"
},
{
"role": "assignee",
"userRef": "sophie.huber@muster-it.example"
}
],
"categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
"checklistDone": 1,
"checklistTotal": 2,
"childCount": 0,
"closedAt": null,
"confidential": false,
"contact": {
"id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
"name": "Katrin Stadler"
},
"createdAt": "2026-11-17T07:12:00Z",
"createdBy": "sophie.huber@muster-it.example",
"customFields": {
"betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
},
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
"name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
},
"description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
"dueAt": "2026-11-17T11:12:00Z",
"dueHasTime": true,
"estimateMinutes": null,
"followUpAt": null,
"forwarding": false,
"handoffs": [],
"id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
"impact": "mittel",
"kbWorthy": false,
"labelIds": [
"9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
"9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
],
"lastAgentPublicAt": "2026-11-17T08:55:00Z",
"lastCustomerAt": "2026-11-17T07:12:00Z",
"number": 1,
"parentId": null,
"pendingSuggestions": 0,
"phase": "active",
"priority": "hoch",
"projectId": null,
"slaDueAt": "2026-11-17T15:12:00Z",
"slaState": "running",
"source": "phone",
"spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
"spentMinutes": 45,
"status": "in_bearbeitung",
"statusChangedAt": "2026-11-17T07:21:00Z",
"summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
"summarySource": "auto",
"teams": [
{
"role": "responsible",
"teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
}
],
"title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
"typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
"updatedAt": "2026-11-17T08:55:00Z",
"updatedBy": "lukas.wimmer@muster-it.example",
"urgency": "hoch",
"version": 6
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/transition' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"comment":"Können Sie bitte kurz prüfen, ob die Gäste in den Zimmern 201 bis 212 wieder stabil verbunden sind?","commentVisibility":"public","status":"wartet_kunde","version":6}'