Welcome to the Vertex Sync public documentation. In order to use the API, please use the latest version of the API.
\nThis API uses OAuth2 authentication with Keycloak. To access protected endpoints, you need to obtain a JWT token and include it in the Authorization header.
Keycloak URLS
\nSample Request to Obtain a JWT Token:
\n POST https://auth-sync.vertex.fi/auth/realms/{realm}/protocol/openid-connect/token\n Content-Type: application/x-www-form-urlencoded\n grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret\n\nSample Response:
\n {\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"expires_in\": 300,\n \"token_type\": \"Bearer\",\n \"scope\": \"entities:write entities:delete\"\n }\n\nUsing the Access Token:
\nInclude the token in the Authorization header:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\n\nA service for handling entities. Entities are general use objects that most of Sync's main features revolve around. Entities typically contain various miscellaneous data, a payload file, a preview file and relations to other entities.
\nEach entity must have a type and a code. The code is often automatically generated by the service but it can be set to specific values during creation as necessary. For example in Vertex BD the code is set to the building's ID. All entities must have a unique type and code combination (multiple entities can have the same combination if they are different revisions of each other). The code is case insensitive for all operations.
\nEntities have a modificationCount field. It is used to implement optimistic locking. Most modifying endpoints requires the field to be given and the operation only succeeds if the modificationCount is equal to the entity's modificationCount in the database.
\nEntities marked as clientSystemFiles are normally hidden from the user. They can be optionally retrieved with a query parameter.
\nEach entity can have a file, a preview file and a thumbnail. The file is the main file of the entity. The preview file can be used to change the preview for a file. The thumbnail is automatically generated from the file or the preview file depending on whether a preview exists. It is a Base64 encoded picture.
\nLabels can be added to entities. They are not freeform strings even though they may look like it. They need to be explicitly created after which they can be used freely in entities. The service renames and deletes labels from entities as necessary.
\nLabels can be automatically added to created entities based on some rules. The rules only activate on entities created after the rules were made. An entity's labels can be modified even if a label came from a rule.
\nEach entity can be blocked for various operations. Only admins and the user who added the block can remove it. OVERWRITE_EVERYONE block prevents all kinds of direct modifications except revisioning. OVERWRITE_OTHERS is akin to a reservation. It allows the current user to do anything while blocking all direct operations from other users. REVISE_EVERYONE only blocks revisioning.
\nWhen an entity is revised the original entity is overwrite blocked and a successor is attached to it. The successor is similar to a copy when it is first created. Revisioning can be likened to backing up an old version of an entity to version history.
\nEntities can have multiple kinds of relations to other entities. The relations are automatically maintained and the different types behave differently under different operations. Relations have no requirements meaning that they can freely form chains, loops, etc. The relation types are similar to their respective UML class diagram relationships.
\nComposition relations thightly couple entities to each other. Most modifying operations also target all other entities linked to the targeted entity via composition. For example deleting an entity also deletes all entities attached to it via composition.
\nAggregation relations are not as tightly coupled as compositions. Most operations do not target entities linked via aggregation. Most operations can however be made to also target aggregation children via a query parameter.
\nAssociations serve as \"links\" between entities. They are practically ignored by the service (but they are still maintained). They only serve a purpose for the client.
\nRelations can be modified in all requests that take in entities in the body. If only one side of a relation is in a request, the relation is copied to the other side. If both sides are part of the request the behavior depends on the relation type: parent relations are completely ignored, children relations always overwritten and associations are asserted to be equal on both sides.
\nEntities can be hidden from specific users or groups with access control. The backend basically ignores any entities the user does not have access to. They cannot be retrieved or modified in any way. Admins can bypass access control as necessary with the optional entities:admin role.
\nBranches can be used to execute multiple operations to a group of entities transactionally. When a branch is created entities can be copied to it. Then the entities inside it can be freely modified, or new entities can be added to the branch. Once the branch is ready it can either be merged to commit all the changes at once or deleted to cancel all changes. If the entities in a branch received modifications outside the branch, merging the branch fails and the branch should be deleted.
\nDeleted entities are automatically moved to the recycle bin. Entities in the recycle bin live for a certain period of time. They can be freely deleted from there or restored. Restored entities attach themselves to the entities they were originally attached to. Revision information is only restored if the previous revision hasn't received breaking changes. Entities in branches do not use the recycle bin.
\nAdmins by default have the same permissions as normal users. They can optionally request the entities:admin scope from the authentication server to gain extra rights. With the scope admins can bypass access control and ignore and manipulate blocks freely.
\nThe service expected a different modificationCount. This means that something modified the entity without the client knowing about it.
\nIf both entities of an association relation are provided in the same request, the associations between the two entities must be identical.
\nAny operation that allows setting labels requires valid labels. The labels must exist and be active. Inactive labels already on an entity do not need to be changed.
\nModifying requests may not modify entities that have been overwrite blocked or reserved by another user.
\nThis API documentation includes both RESTful endpoints and real-time communication endpoints via SignalR.
\nVertex Sync uses SignalR for real-time web functionality, enabling the server to send asynchronous notifications to client-side web applications. The SignalR endpoints, specifically under /(hubs)/NotificationHub, are designed for real-time notifications and cannot be interacted with via standard HTTP requests.
For more detailed information on how to establish a SignalR connection and interact with these real-time endpoints, please refer to the official SignalR documentation.
\nWithin the SignalR framework of our application, users can join different groups to receive targeted real-time notifications. Below are the formats used for different notification scenarios:
\nSingle User Notifications: For notifications specific to a single user, groups are named using the user's ID and their interests in the format USER_[userId]_INTERESTS. For example, a user with the ID \"foo\" would be part of the group USER_foo_INTERESTS.
Entity Change Notifications: To receive notifications about changes to any entity within the application, users should join the group named ALL_ENTITY_CHANGES.
System-Wide Notifications: For notifications that are relevant across the entire system, the group name SYSTEM is used.
Whether to return the thumbnails for the entities
\n","type":"text/plain"},"key":"ignoreThumbnails","value":"false"}],"variable":[{"id":"169f7a00-dab4-452b-b5c2-3aff78c3f00d","description":{"content":"(Required) The entity id to use
\n","type":"text/plain"},"type":"any","value":"