REST API Reference
All modeler REST endpoints are mounted under the base path configured by cibseven.webclient.services.basePath (default: /services/v1), appended with /modeler.
Base URL: {basePath}/modeler
All endpoints require an authenticated user who holds the application ACCESS permission for the modeler resource — the same permission that decides whether the modeler is shown in the UI. See Authentication. Changed in 2.3.0.
Diagrams (BPMN / DMN)
A write refuses a value longer than its column with 400 Bad Request rather than letting the database fail: name holds 255 characters, processkey 100 and description 150.
List Diagrams
GET /modeler/processes
Returns a paginated, reduced list of diagram metadata (excludes raw XML bytes).
Query Parameters:
| Parameter | Required | Description |
|---|---|---|
firstResult |
Yes | Zero-based offset for pagination |
maxResults |
Yes | Maximum number of results to return |
diagramType |
No | Filter by type: bpmn-c7, dmn, etc. |
keyword |
No | Filter by name (case-insensitive substring) |
Response: 200 OK — Array of ProcessDiagramReduce objects.
List Unified Diagrams
GET /modeler/unified-diagrams
Returns a combined list of BPMN diagrams and forms in a unified format.
Query Parameters:
| Parameter | Required | Description |
|---|---|---|
firstResult |
Yes | Pagination offset |
maxResults |
Yes | Maximum results |
keyword |
No | Name filter |
type |
No | diagram or form |
folderId |
No | Only the models in this folder; every folder when absent. Available from 2.3.0 |
Each entry carries the folderId of the folder it is filed in, from 2.3.0.
Get Diagram by ID
GET /modeler/process/{id}
Returns the full ProcessDiagramEntity including metadata.
Get Diagram XML by ID
GET /modeler/process/{id}/data
Returns the raw diagram bytes (BPMN or DMN XML) as application/octet-stream.
Create Diagram from File Upload
POST /modeler/process/create
Uploads a .bpmn or .dmn file and saves it as a new diagram.
Form Parameters:
| Parameter | Required | Description |
|---|---|---|
file |
Yes | Multipart file upload (.bpmn or .dmn) |
overwrite |
Yes | true to overwrite an existing diagram with the same name |
folderId |
Yes | The folder to file the diagram in. Required from 2.3.0 |
Save Diagram (form data)
POST /modeler/process/save
Creates or updates a diagram from form-encoded data.
Form Parameters: name, processkey, description, active, type, diagram (multipart file), folderId
folderId names the folder the diagram is filed in and is required from 2.3.0: a diagram lives in exactly one folder, and none is chosen for the caller.
Save Diagram (JSON body)
POST /modeler/process/save/object
Creates or updates a diagram from a JSON body. If the entity’s id matches an existing record it is updated; otherwise a new record is created.
Request Body: ProcessDiagramEntity JSON object. A new diagram needs its folderId from 2.3.0; an update leaves the diagram where it is when the field is absent.
Update Diagram
POST /modeler/process/update
Updates an existing diagram by ID with new metadata and XML.
Form Parameters: id, name, processkey, description, active, type, diagram (multipart file)
Find Diagram by Name
POST /modeler/process/find-by-name/data
Returns the raw diagram bytes for the diagram with the given name.
Query Parameters: name
Find Diagram by Process Key
POST /modeler/process/find-by-key/data
Returns the raw diagram bytes for the diagram with the given process key.
Query Parameters: key
Delete Diagram
DELETE /modeler/process/delete/{id}
Permanently deletes the diagram with the given ID.
Move Diagram to a Folder
POST /modeler/process/{id}/move
Available from 2.3.0.
Body:
| Field | Required | Description |
|---|---|---|
folderId |
Yes | The folder to file the diagram in |
The diagram keeps its id and its process key, so deployments made from it and links to it still resolve.
Response: 200 OK — the moved ProcessDiagramEntity. 400 Bad Request when no folder is named, 404 Not Found when the diagram or the folder does not exist.
Copy Diagram into a Folder
POST /modeler/process/{id}/copy
Available from 2.3.0.
Body:
| Field | Required | Description |
|---|---|---|
folderId |
Yes | The folder to put the copy in |
processkey |
Yes | The process key of the copy |
name |
No | Name of the copy; the name of the original when absent |
A copy needs a process key of its own: the engine resolves a process by its key, so two diagrams cannot share one.
Response: 200 OK — the created copy. 400 Bad Request when no key is given or when the key is already taken.
Deployment
Deploy Diagram by File
POST /modeler/deployment/create
Deploys an uploaded diagram file directly to the CIB seven engine.
Form Parameters: deployment-name, deployment-source, deploy-changed-only, file (multipart)
Deploy Diagram by ID
POST /modeler/deployment/create/{id}
Retrieves a stored diagram by its database ID and deploys it to the engine.
Path Parameters: id (diagram database ID)
Deploy Diagram by Key (Reduce)
POST /modeler/deployment/create/reduce
Retrieves a stored diagram by process key and deploys it.
Form Parameters: deploymentName (process key), file
Check Deployment Connectivity
GET /modeler/deployment
Checks that the authenticated user has access to the deployment endpoint. Returns 200 OK if authorized.
Start Process
POST /modeler/deployment/start/{key}
Starts a new instance of the deployed process definition identified by key.
Path Parameters: key (process definition key)
Request Body: JSON map of process variables
Sessions
Open Session
POST /modeler/session/save
Records that the current user has opened a diagram or form for editing.
Form Parameters: type (diagram or form), id (diagram or form ID), diagram (current XML snapshot)
Close Session
POST /modeler/session/close
Closes one or more editing sessions for the current user.
Form Parameters: sessionId (comma-separated list), type (diagram or form)
Check Diagram Session
GET /modeler/process/session/check/{id}
Checks whether another user currently has the diagram open.
Path Parameters: id (diagram ID)
Response:
message value |
Meaning |
|---|---|
NO_SESSION |
No one else has this diagram open |
SAME_USER |
The current user already has it open |
SESSION_FOUND |
Another user has it open — response includes userId and openedAt |
Check Form Session
GET /modeler/form/session/check/{id}
Same as above but for forms.
Forms
A write refuses a value longer than its column with 400 Bad Request: formId holds 100 characters and description 150.
List Forms
GET /modeler/forms
Returns a paginated list of saved forms.
Query Parameters: firstResult, maxResults, keyword
Get Form Schema by ID
GET /modeler/form/{id}/data
Returns the form JSON schema as application/json.
Save Form
POST /modeler/form/save
Creates a new form with the given ID and schema.
Form Parameters: formid, form_schema (multipart JSON file), folderId
folderId names the folder the form is filed in and is required from 2.3.0.
Update Form
POST /modeler/form/update
Updates an existing form.
Form Parameters: id, formid, form_schema (multipart JSON file)
Delete Form
DELETE /modeler/form/delete/{id}
Permanently deletes the form and its session records.
Move Form to a Folder
POST /modeler/form/{id}/move
Available from 2.3.0.
Body:
| Field | Required | Description |
|---|---|---|
folderId |
Yes | The folder to file the form in |
The form keeps its id and its form id.
Response: 200 OK — the moved FormEntity.
Copy Form into a Folder
POST /modeler/form/{id}/copy
Available from 2.3.0.
Body:
| Field | Required | Description |
|---|---|---|
folderId |
Yes | The folder to put the copy in |
formId |
Yes | The form id of the copy |
A copy needs a form id of its own: a form is referenced by its form id, so two forms cannot share one.
Response: 200 OK — the created copy. 400 Bad Request when no form id is given or when it is already taken.
Folders
Available from 2.3.0. Folders organize stored diagrams and forms; every model is filed in exactly one. A folder without a parent is at the top level, which holds folders only — a model is never stored there.
List Folders
GET /modeler/folders
Returns every folder, each carrying the parentId of the folder holding it, so one call is enough to build the whole tree. The list is empty when every folder has been deleted; listing creates nothing, not even the caller’s own folder (see Get Own Folder).
Response: 200 OK — array of FolderEntity objects. Each carries userFolder, which is true for the folder of a user: a folder at the top level named after the user who created it.
Get Folder
GET /modeler/folders/{id}
Response: 200 OK — the FolderEntity. 404 Not Found when there is none with that id.
Get Folder Contents
GET /modeler/folders/{id}/contents
Counts what the folder holds through its whole subtree, for a confirmation before deleting it.
Response: 200 OK — { "folders": 2, "diagrams": 7, "forms": 1 }
Get Own Folder
POST /modeler/folders/user-folder
Returns the caller’s own folder, the folder at the top level named after the caller’s user ID, and creates it on the first call. The modeler calls it when its start page opens, so a user gets a folder on the first visit rather than at login. A folder at the top level that already carries the user ID is returned as it is.
A user’s folder cannot be renamed, moved or deleted except by an administrator, a user granted the All permission on the System resource.
Response: 200 OK — { "folder": { ... }, "manageUserFolders": false }
| Field | Description |
|---|---|
folder |
The caller’s folder, a FolderEntity |
manageUserFolders |
Whether the caller may rename, move and delete the folders of users |
Create Folder
POST /modeler/folders
Body:
| Field | Required | Description |
|---|---|---|
name |
Yes | Name of the folder, unique among the folders beside it |
parentId |
No | The folder to create it in; created at the top level when absent |
Response: 200 OK — the created folder. 400 Bad Request when the name is empty, longer than 255 characters, or already taken in that place.
Rename or Move Folder
PUT /modeler/folders/{id}
Body: send name, parentId, or both.
| Field | Description |
|---|---|
name |
The new name |
parentId |
The folder to move it into; null moves it to the top level |
The folder keeps its id, so everything below it stays reachable. A folder cannot be moved into itself or into one of its own subfolders. Sending both fields applies them together: if the move is refused, the folder is not renamed either.
Response: 200 OK — the updated folder. 400 Bad Request when the name is taken or the move would put the folder inside itself. 403 Forbidden when the folder is the folder of a user and the caller is not an administrator.
Delete Folder
DELETE /modeler/folders/{id}
Deletes the folder with everything below it: subfolders, diagrams and forms. This cannot be undone — call the contents endpoint first and confirm with the user. Deployed processes are unaffected.
Response: 200 OK — what was removed, in the shape the contents endpoint returns. 403 Forbidden when the folder is the folder of a user and the caller is not an administrator.
Chat (Enterprise Edition)
Enterprise Feature
Chat endpoints are only available in the enterprise edition when cibseven.webclient.modeler.enabled: true.
Chat endpoints are mounted under a separate base path: {basePath}/chat.
Base URL: {basePath}/chat
Get Message History
GET /chat/{roomId}/history
Returns chat messages for a room in reverse chronological order (newest first).
Path Parameters:
| Parameter | Description |
|---|---|
roomId |
Composite room identifier — see Real-time Chat |
Query Parameters:
| Parameter | Required | Default | Description |
|---|---|---|---|
limit |
No | 100 |
Maximum number of messages to return |
before |
No | — | ISO-8601 datetime — return only messages created before this timestamp (for pagination) |
elementId |
No | — | Filter messages by the BPMN element ID they are attached to |
Response: 200 OK — Array of message objects including id, roomId, userId, displayName, content, createdAt, editedAt, and optionally elementId. Soft-deleted messages are excluded.
Send Message
POST /chat/{roomId}
Creates a new message in the room. This endpoint is the primary way to send messages in the long-polling transport. In WebSocket mode, messages can also be published over STOMP (see Real-time Chat).
Path Parameters:
| Parameter | Description |
|---|---|
roomId |
Composite room identifier |
Request Body:
| Field | Required | Description |
|---|---|---|
content |
Yes | Message text (must not be blank) |
elementId |
No | BPMN element ID to attach the message to a specific element |
Response: 200 OK — The created message object.
Get Room Presence
GET /chat/{roomId}/presence
Returns the set of users currently active in the room. In the long-polling transport, presence is backed by the database and reflects users who have polled within the last ~60 seconds. In the WebSocket transport, it reflects users currently subscribed to the room’s WebSocket topic.
Path Parameters:
| Parameter | Description |
|---|---|
roomId |
Composite room identifier |
Response: 200 OK — Array of presence objects:
| Field | Description |
|---|---|
userId |
Authenticated user ID |
displayName |
User’s display name |
Long-Poll for Events
GET /chat/{roomId}/poll?since={cursor}
Long-polling endpoint used by the longpolling transport. The server holds the request for up to ~25 seconds and returns early when new events are available. The client immediately re-polls after each response.
Calling this endpoint also records a presence heartbeat for the authenticated user.
Path Parameters:
| Parameter | Description |
|---|---|
roomId |
Composite room identifier |
Query Parameters:
| Parameter | Required | Description |
|---|---|---|
since |
No | Opaque cursor returned by the previous poll. Omit on the first poll to establish a baseline — the server returns an empty event list and the current cursor. |
Response: 200 OK
| Field | Description |
|---|---|
cursor |
Opaque server-owned timestamp. Pass back as since on the next poll. |
events |
Array of change events since the cursor. Empty if nothing changed during the hold. Each event has an op field (create, update, or delete) and a message object. |
presence |
Current presence snapshot for the room — same format as Get Room Presence. |