Project Item API

The Project Item API allows you to create, read, update, and delete items within a project. Items are visual elements placed on a project map such as labels, shapes, images, documents, and more.

Base URL

All endpoints use the following base path:

/api/v2/projects/{projectId}/item

Authentication

All requests require a valid API token. You can generate an API token at https://account.deon.cloud/account/api-tokens. Include it as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-token>

Finding Your IDs

Project ID and Item ID

The easiest way to find your projectId and itemId is directly in the DEON Desktop App. Click on any item on the canvas to select it — a context menu appears. Open the ... menu (more options) in that context menu. From there, select any GET action (e.g. GET Text) to copy the full API URL for reading a property, or select PATCH to copy the URL for updating the item. Both URLs contain the projectId and itemId:

https://api.deon.cloud/api/v2/projects/{projectId}/item/{itemId}/text
https://api.deon.cloud/api/v2/projects/{projectId}/item/{itemType}/{itemId}

Project Coordinates

To get an arbitrary coordinate on the canvas, right-click anywhere on the canvas to open the Quick Menu and click Copy project-coordinate. The coordinate is copied to your clipboard as JSON:

{"x": 17003.816, "y": -1282.033}

Common Endpoints

Method	Path	Description
POST	/{parent}/{itemType}	Create a new item
POST	/{parent}/{itemType}/file	Create a new item with a file upload
GET	/{itemId}	Get an item by ID
GET	/{itemId}/{property}	Get a specific property value from an item
PATCH	/{itemType}/{itemId}	Update an existing item
DELETE	/{itemId}	Delete an item

Path Parameters

Parameter	Type	Description
projectId	string (GUID)	The ID of the project.
parent	string	The parent container for the item. Accepted values: inbox, panel, or a custom parent item ID.
itemType	string	The type of item. See Item Types below.
itemId	string (GUID)	The ID of the item.

Item Types

The following item types are supported:

Item Type	Description
label	Text label with customizable font, color, and alignment.
sticky-note	A preset label styled as a sticky note.
shape	Geometric shape with fill and stroke options.
connector	Line connector between items or points with customizable style and decorators.
web	Embedded web page via URL.
image	Raster image (JPEG, PNG, GIF, WebP). Requires file upload.
document	Document file (PDF, Word, PowerPoint, etc.). Requires file upload.
svg	Vector image (SVG). Requires file upload.

Common Properties (Base)

All item types share the following base properties:

Property	Type	Required	Default	Description
position	object	No	{ x: 0, y: 0 }	Position on the map. Object with x and y number fields.
size	object	Varies	Varies	Size of the item. Object with width and height number fields. Minimum value: 5 per dimension.
scale	number	No	1	Scale factor. Must be greater than 0.
angle	number	No	0	Rotation angle in degrees. Must be between 0 and 360.

Response Format

All create, update, and delete operations return an ItemResponseDto:

{
  "itemId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Get Individual Property

You can retrieve a specific property value from an item without fetching the entire item DTO. This is useful when you only need to check or display a single property value.

GET /api/v2/projects/{projectId}/item/{itemId}/{property}

Parameters

Parameter	Type	Description
projectId	string (GUID)	The ID of the project.
itemId	string (GUID)	The ID of the item.
property	string	The name of the property to retrieve (case-insensitive).

Property Names

Property names are case-insensitive and can be specified in any casing (e.g., text, Text, or TEXT all work). Common properties available for all items include:

• position - Returns an object with x and y fields
• size - Returns an object with width and height fields
• scale - Returns a number
• angle - Returns a number

Each item type also exposes its specific properties. For example:

• Label: text, fontSize, fontFamily, textColor, backgroundColor, horizontalTextAlignment, verticalTextAlignment
• Shape: shapeType, fillColor, strokeColor, strokeWidth
• Connector: type, strokeColor, strokeThickness, cornerPoints, radius, startPoint, endPoint
• Image: fileName, mimeType, fileSize

Refer to each item type's documentation for the complete list of available properties.

Examples

Get a label's text:

curl -X GET "https://api.deon.cloud/api/v2/projects/{projectId}/item/{itemId}/text" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Response:

"Hello World"

Get an item's angle:

curl -X GET "https://api.deon.cloud/api/v2/projects/{projectId}/item/{itemId}/angle" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Response:

45

Get an item's size (complex object):

curl -X GET "https://api.deon.cloud/api/v2/projects/{projectId}/item/{itemId}/size" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Response:

{
  "width": 300,
  "height": 150
}

JavaScript example:

// Get a specific property value
const response = await fetch(
  `https://api.deon.cloud/api/v2/projects/${projectId}/item/${itemId}/text`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json",
    },
  }
);

const textValue = await response.json();
console.log(textValue); // "Hello World"

Error Responses

HTTP Status	Description
400	Property name is invalid or not available for this item type.
404	Project or item not found.
403	User does not have access to the project.

JSON Response Casing

By default, JSON responses use PascalCase property names (matching the server-side DTO definitions). You can override the casing of JSON property names by appending the jsonCasing query parameter to any request that returns JSON.

GET /api/v2/projects/{projectId}/item/{itemId}?jsonCasing=camel

Supported Values

Value	Example Output	Description
default	"ItemId"	PascalCase — original DTO property names (server default).
camel	"itemId"	camelCase
pascal	"ItemId"	PascalCase (same as default)
snake	"item_id"	snake_case
kebab	"item-id"	kebab-case

The parameter is case-insensitive, so jsonCasing=Camel, jsonCasing=CAMEL, and jsonCasing=camel are all equivalent.

note

This only affects JSON responses (Accept: application/json). Other response formats such as MessagePack are not affected by this parameter.

Example

Request:

GET /api/v2/projects/abcd1234-.../item/efgh5678-...?jsonCasing=snake HTTP/1.1 Accept: application/json Authorization: Bearer <your-api-token>

Response:

{
  "item_id": "efgh5678-...",
  "position": { "x": 100, "y": 200 },
  "size": { "width": 300, "height": 150 },
  "scale": 1,
  "angle": 0
}

Error Handling

HTTP Status	Reason	Description
400	Malformed Request	Validation failed or invalid item type.
404	Entity Not Found	Project or item not found.
403	Forbidden	User does not have access to the project.