Label

A label is a text element placed on the project map. Labels support customizable font, color, alignment, and auto-sizing behavior.

Item type: label

Properties

Property	Type	Required	Updatable	Default	Description
position	object	No	Yes	{ x: 0, y: 0 }	Position with x and y fields.
size	object	No	Yes	Auto-sized	Size with width and height fields. See auto-size rules below.
scale	number	No	Yes	1	Scale factor. Must be > 0.
angle	number	No	Yes	0	Rotation angle (0–360).
text	string	Yes	Yes	—	The label text content. Can be plain text or valid HTML.
fontSize	number	No	Yes	Theme default	Font size in points. Must be ≥ 1.
fontFamily	string	No	Yes	Theme default	Font family name.
textColor	string	No	Yes	"#FFFFFF"	Text color as a hex string: "#RRGGBB", "#AARRGGBB" (alpha first) or "#RGB"; CSS forms such as rgb() and named colors are rejected.
backgroundColor	string	No	Yes	"#444444"	Background color as a hex string: "#RRGGBB", "#AARRGGBB" (alpha first) or "#RGB"; CSS forms such as rgb() and named colors are rejected.
isAutoSizeWidth	boolean	No	Yes	true	Whether the width is automatically sized to fit text.
isAutoSizeHeight	boolean	No	Yes	true	Whether the height is automatically sized to fit text.
autoSize	string	No	Yes	"both"	Both auto-size flags as one choice: "none" (a fixed box), "width" (one line that grows right, at a fixed height), "height" (wraps at size.width and grows down) or "both" (one line that grows both ways). The same values the MCP tools take; returned when you read the label. A flag sent with it must agree with it.
horizontalTextAlignment	string	No	Yes	"Left"	Horizontal text alignment: "Left", "Center", "Right".
verticalTextAlignment	string	No	Yes	"Top"	Vertical text alignment: "Top", "Center", "Bottom".

Auto-Size Rules

• When isAutoSizeWidth is true (default), size.width must be 0 or omitted.
• When isAutoSizeHeight is true (default), size.height must be 0 or omitted.
• When auto-size is disabled for a dimension, the corresponding size value must be ≥ 5.
• A label wraps its text only when isAutoSizeWidth is false and size.width is greater than 0. While isAutoSizeWidth is true the label ignores size.width entirely and lays its text out on a single line.
• Never combine isAutoSizeWidth: false with size.width: 0 — the label renders nothing.
• autoSize sets both flags at once, and the rules above apply to the flags it stands for: "height" needs size.width ≥ 5, "none" needs both.

Auto-Size on update

PATCHing size on a label also updates both auto-size flags, deriving each from the matching dimension (0 means that axis auto-sizes). This keeps the two consistent: updating size alone would otherwise persist a width the renderers ignore. To keep an axis auto-sized while changing its stored size, send the flag explicitly in the same request — an explicit value always wins over the derived one.

PATCHing autoSize sets both flags and the size that fits them: an axis that grows goes to 0, and a fixed axis keeps the size it has, or takes size when you send it in the same request. An axis that grows today stores no usable size, so fixing it needs size too:

{ "autoSize": "height", "size": { "width": 300, "height": 0 } }

Defaults compared with MCP

The MCP create_item tool picks different defaults for a label: a text color that reads well on the canvas, and no background (#00000000). The REST API keeps #FFFFFF text on a #444444 background. Send textColor and backgroundColor to get the same label from both.

Create

Creates a new label item in the project.

POST /api/v2/projects/{projectId}/item/{parent}/label

curl

curl -X POST "https://api.deon.cloud/api/v2/projects/{projectId}/item/inbox/label" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello World",
    "position": { "x": 100, "y": 200 },
    "fontSize": 16,
    "textColor": "#FFFFFF",
    "backgroundColor": "#0078D4",
    "horizontalTextAlignment": "Center",
    "verticalTextAlignment": "Center"
  }'

JavaScript

const response = await fetch(
  `https://api.deon.cloud/api/v2/projects/${projectId}/item/inbox/label`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Hello World",
      position: { x: 100, y: 200 },
      fontSize: 16,
      textColor: "#FFFFFF",
      backgroundColor: "#0078D4",
      horizontalTextAlignment: "Center",
      verticalTextAlignment: "Center",
    }),
  }
);

const data = await response.json();
console.log(data.itemId);

Response

{
  "itemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Update

Updates an existing label item. Only include the properties you want to change.

PATCH /api/v2/projects/{projectId}/item/label/{itemId}

curl

curl -X PATCH "https://api.deon.cloud/api/v2/projects/{projectId}/item/label/{itemId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Updated Text",
    "fontSize": 20,
    "backgroundColor": "#FF5722"
  }'

JavaScript

const response = await fetch(
  `https://api.deon.cloud/api/v2/projects/${projectId}/item/label/${itemId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Updated Text",
      fontSize: 20,
      backgroundColor: "#FF5722",
    }),
  }
);

const data = await response.json();
console.log(data.itemId);

Response

{
  "itemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}