Endpoint Reference

This page lists REST API routes that complement the screens described elsewhere in the documentation. The Swagger page on your Profinity instance lists every route and the parameters it accepts, and Profinity REST APIs explains how to authenticate. Each route needs the same permission as the matching screen.

Alerts

Routes under /api/v2/Alerts return and manage the alerts shown in the Alerts Log.

Method	Route	Body
GET	/api/v2/Alerts/Active	None. Optional query values componentId, tagPrefix, unacknowledgedOnly and level.
GET	/api/v2/Alerts/History	None. Optional query values componentId, tagPrefix, pageIndex, pageSize, level, fromUtc, and toUtc.
POST	/api/v2/Alerts/Ack	{ "ruleId": "...", "tagId": "..." }
POST	/api/v2/Alerts/Unack	{ "ruleId": "...", "tagId": "..." }
POST	/api/v2/Alerts/Silence	{ "ruleId": "...", "tagId": "...", "durationMinutes": 60 }

Through the API a silence can last from 1 to 1440 minutes (24 hours), and a request outside that range is refused with "durationMinutes must be between 1 and 1440." The Unack route is the same revert that the Unacknowledge alert button uses.

Collections and derived tags

Method	Route	Purpose
GET, PUT	/api/v2/Tags/Collections	Reads or saves the collections document, with JSON request and response bodies. Reading needs View tag collections and saving needs Modify tag collections.
GET, PUT	/api/v2/Tags/DerivedTags	Reads or saves the derived tags document, with the same permissions as collections.

Profinity AI

Method	Route	Purpose
POST	/api/v2/Ai/Chat	Streams a chat response for the calling user, using the instance's Profinity AI configuration.

Component and collection security

The routes below work on the active profile only, and there is no route to edit security for a profile that is not currently loaded. A GET response includes an unresolvedRoles list alongside mode and allowedRoles, and a PUT accepts only mode and allowedRoles. Refer to Component and Collection Security for the policy itself.

Method	Route	Permission	Purpose
GET, PUT	/api/v2/ActiveProfile/components/{componentName}/security	Security administration	Reads or writes the security policy for a component on the active profile. {componentName} is the component's display name.
GET, PUT	/api/v2/ActiveProfile/collections/{collectionId}/security	Security administration	Reads or writes the security policy for a collection on the active profile, including the reserved All collection.

Account resets

These routes need the Security administration permission, and match Reset MFA and Reset Password in Managing Users.

Method	Route	Purpose
POST	/api/v2/Users/{username}/TwoFactor/Reset	Clears the user's authenticator enrolment.
POST	/api/v2/Users/{username}/Password/Reset	Requires a password change at the next sign-in and signs out active sessions.

Tag Relay

Method	Route	Purpose
POST	/api/v2/Relay/snapshot	Receives a snapshot from a Tag Relay Sender that uses HTTPS. The caller needs a JSON Web Token (JWT) for a user with the Receive external tags permission (or Admin), the request body can be up to 5 MB, and an instance accepts relay posts for only one Tag Relay Receiver set to HTTPS.

Themes

The theme is read-only through the API. GET /api/v2/Themes is anonymous, so the sign-in page can use it before a user has authenticated, and returns appTitle, hasCustomTheme and a logos object with main, login and favicon URLs. The generated stylesheet is served from /Themes/theme.css, and each asset from /Themes/Assets/{file}. Changes are made by editing the theme file, as described in Themes and Branding.