Shape

A shape is a geometric element on the project map with configurable type, fill, and stroke.

Item type: shape

Properties

Property	Type	Required	Updatable	Default	Description
position	object	No	Yes	{ x: 0, y: 0 }	Position with x and y fields.
size	object	Yes	Yes	—	Size with width and height fields. Min 5 per dimension.
scale	number	No	Yes	1	Scale factor. Must be > 0.
angle	number	No	Yes	0	Rotation angle (0–360).
type	string	No	No	"Rectangle"	Shape type. Immutable after creation. See Shape Types.
fillColor	string	No	Yes	Transparent	Fill color as a hex string: "#RRGGBB", "#AARRGGBB" (alpha first) or "#RGB"; CSS forms such as rgb() and named colors are rejected.
strokeColor	string	No	Yes	"#FFFFFF"	Stroke (border) color as a hex string: "#RRGGBB", "#AARRGGBB" (alpha first) or "#RGB"; CSS forms such as rgb() and named colors are rejected.
strokeThickness	number	No	Yes	2	Stroke width in pixels. Must be ≥ 0.
adjustmentValues	number[]	No	Yes	[]	Shape-specific adjustment values. Each value must be ≥ 0.
cornerRadius	number	No	Yes	The shape's own	Corner radius in world units, for the round-corner shapes only. Must be ≥ 0. See Corner Radius.

warning

The type property is immutable — it can only be set during creation and cannot be changed via update.

Corner Radius

cornerRadius sets rounded corners in world units, so shapes of different sizes get the same corners. It applies to the shapes below; any other shape rejects it.

Type	Corners it rounds
RoundedRectangle	all four (default: a tenth of the shorter side)
OneRoundCornerRectangle	top-right
TwoSameSideRoundCornerRectangle	both top corners
TwoDiagonalRoundCornerRectangle	top-left and bottom-right
OneSnipOneRoundCornerRectangle	top-left

• The server stores it as the first of adjustmentValues, a fraction of the shorter side of the drawn shape (size times scale). When a request sends both, cornerRadius wins over that first value and the others are kept.
• The radius is capped at half the shorter side, where a RoundedRectangle becomes a pill.
• An update converts it at the size and scale sent in the same request, or else at the ones the shape has.
• A later size change scales the corners with the shape. To resize and keep the corners, send size and cornerRadius in the same PATCH.
• GET returns the radius the corners are drawn with. It is null for other shapes.

Shape Types

The following shape types are supported (case-insensitive):

Type	Description
Rectangle	Standard rectangle
Ellipse	Ellipse / circle
RoundedRectangle	Rectangle with rounded corners
Triangle	Equilateral triangle
RightTriangle	Right-angled triangle
Diamond	Diamond / rhombus
Hexagon	Regular hexagon
Heptagon	Regular heptagon
Octagon	Regular octagon
Decagon	Regular decagon
Dodecagon	Regular dodecagon
Pentagon	Regular pentagon
Parallelogram	Parallelogram
Trapezoid	Trapezoid
Plus	Plus / cross shape
Donut	Ring / donut shape
Heart	Heart shape
LightningBolt	Lightning bolt
Star4	4-pointed star
Star5	5-pointed star
Star6	6-pointed star
DirectionArrow	Bidirectional arrow
DirectionArrowRight	Right-pointing direction arrow
DirectionArrowLeft	Left-pointing direction arrow
RightArrow	Right arrow
LeftArrow	Left arrow
UpArrow	Up arrow
DownArrow	Down arrow
LeftRightArrow	Left-right arrow
UpDownArrow	Up-down arrow
QuadArrow	Four-directional arrow
LeftRightUpArrow	Left-right-up arrow
StripedRightArrow	Striped right arrow
NotchedRightArrow	Notched right arrow
Plaque	Plaque shape
Frame	Frame shape
HalfFrame	Half-frame shape
Corner	Corner shape
OneSnipCornerRectangle	Rectangle with one snipped corner
TwoSameSideSnipCornerRectangle	Rectangle with two same-side snipped corners
TwoDiagonalSnipCornerRectangle	Rectangle with two diagonal snipped corners
OneSnipOneRoundCornerRectangle	Rectangle with one snipped and one rounded corner
OneRoundCornerRectangle	Rectangle with one rounded corner
TwoSameSideRoundCornerRectangle	Rectangle with two same-side rounded corners
TwoDiagonalRoundCornerRectangle	Rectangle with two diagonal rounded corners

Create

Creates a new shape item in the project.

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

curl

curl -X POST "https://api.deon.cloud/api/v2/projects/{projectId}/item/inbox/shape" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Ellipse",
    "position": { "x": 200, "y": 300 },
    "size": { "width": 150, "height": 150 },
    "fillColor": "#4CAF50",
    "strokeColor": "#2E7D32",
    "strokeThickness": 3
  }'

JavaScript

const response = await fetch(
  `https://api.deon.cloud/api/v2/projects/${projectId}/item/inbox/shape`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "Ellipse",
      position: { x: 200, y: 300 },
      size: { width: 150, height: 150 },
      fillColor: "#4CAF50",
      strokeColor: "#2E7D32",
      strokeThickness: 3,
    }),
  }
);

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

Response

{
  "itemId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Update

Updates an existing shape. Only include the properties you want to change. The type property cannot be updated.

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

curl

curl -X PATCH "https://api.deon.cloud/api/v2/projects/{projectId}/item/shape/{itemId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fillColor": "#FF9800",
    "strokeThickness": 5
  }'

JavaScript

const response = await fetch(
  `https://api.deon.cloud/api/v2/projects/${projectId}/item/shape/${itemId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fillColor: "#FF9800",
      strokeThickness: 5,
    }),
  }
);

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

Response

{
  "itemId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Read

GET /api/v2/projects/{projectId}/item/{itemId} returns the shape with every property above. For a round-corner shape cornerRadius is the radius its corners are drawn with; GET /api/v2/projects/{projectId}/item/{itemId}/cornerRadius returns just that number. An excerpt of the response:

{
  "type": "RoundedRectangle",
  "position": { "x": 200, "y": 300 },
  "size": { "width": 1500, "height": 1500 },
  "adjustmentValues": [0.04933333333333333],
  "cornerRadius": 74
}