REST API
LoyJoy offers a REST API for programmatically accessing process definitions, home views, catalogs, articles, notifications and variables.
The API is in beta and might change in the future.
Authorization API
All of the following endpoints require authorization with a bearer access token. Such an access token can be retrieved at cloud.loyjoy.com in the tenant settings at tab API. Please note that the access token is associated to the user account and tenant it has been generated for. Thus removing an user from a tenant invalidates the access token.
Process Definitions API
List All Process Definitions as JSON
Returns a JSON list of all process definitions in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/process-definition" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Process Definition as JSON
Returns a JSON representation of the process definition in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/process-definition/<PROCESS_DEFINITION_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Process Definition as XML
Returns a XML representation of the process definition in the tenant. This is the XML serialization as executed by the LoyJoy runtime engine. Please note that the XML schema might change in the future with further development of LoyJoy functionality, i.e. the XML schema does not constitute an API.
curl -X GET "https://app-stable.loyjoy.com/api/process-definition/xml/<PROCESS_DEFINITION_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/xml"
Start a Process Definition
Starts a process definition programmatically. This call optionally can ingest variables, and then returns the resulting variables. The process instance will halt if the process definition expects user input. E.g. if the process definition contains a Proceed process module it will halt on the proceed question. Halting can be prevented by using only process modules that do not require user interaction.
curl -X POST "https://app-stable.loyjoy.com/api/process-definition/start/<PROCESS_DEFINITION_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "variables": { "some_var": { "value": "some_value" } }, "withVariablesInReturn": true }'
Home Views API
List All Views as JSON
Returns a JSON list of all views in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/view" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Home View as JSON
Returns a JSON representation of the view in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/view/<VIEW_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Home View as XML
Returns a XML representation of the view in the tenant. Please note that the XML schema might change in the future with further development of LoyJoy functionality, i.e. the XML schema does not constitute an API.
curl -X GET "https://app-stable.loyjoy.com/api/view/xml/<VIEW_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/xml"
Catalogs API for Knowledge database
List All Catalogs as JSON
Returns a JSON list of all catalogs in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/catalog" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Catalog as JSON
Returns a JSON representation of the catalog in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/catalog/<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Catalog as XML
Returns a XML representation of the catalog in the tenant. Please note that the XML schema might change in the future with further development of LoyJoy functionality, i.e. the XML schema does not constitute an API.
curl -X GET "https://app-stable.loyjoy.com/api/catalog/xml/<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/xml"
Delete a Catalog
Deletes the catalog in the tenant.
curl -X DELETE "https://app-stable.loyjoy.com/api/catalog/<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Post a Catalog
Posts a JSON representation of a catalog into the tenant.
curl -X POST "https://app-stable.loyjoy.com/api/catalog" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "name": "Some Catalog" }'
Articles API
List All Articles of a Catalog as JSON
Returns a JSON list of all articles of a knowledge catalog in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/article?catalog_id=<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get an Article of a Catalog as JSON
Returns a JSON representation of the article of a catalog in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/article/<ARTICLE_ID>?catalog_id=<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Delete an Article of a Catalog
Deletes the article of a catalog in the tenant.
Please note, that you can delete only 1 article per second and catalog. This implies that you have to throttle your client or the API will throw HTTP status 500 errors after several writes.
curl -X DELETE "https://app-stable.loyjoy.com/api/article/<ARTICLE_ID>?catalog_id=<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Post an Article of a Catalog as JSON
Posts a JSON representation of the article into a catalog in the tenant.
Please note, that you can write only 1 article per second and catalog. This implies that you have to throttle your client or the API will throw HTTP status 500 errors after several writes.
curl -X POST "https://app-stable.loyjoy.com/api/article?catalog_id=<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "name": "Some Article", "text": { "de": "Some German Text", "de-x-formal": "Some German Formal Text", "en": "Some English Text" }, "title": { "de": "Some German Title" }, "source_url": "https://www.example.org" }'
Web Notifications API
Post a Web Notification as JSON
Posts a JSON representation of a web notification. The notification will be shown on the home view of the given device ID, if a notifications widget is contained on the home view. The device ID can be determined with the function call deviceId().
curl -X POST "https://app-stable.loyjoy.com/api/web_notification" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "body": "Some Body", "title": "Some Title", "device_id": "00000000-0000-0000-0000-000000000000", "due_at": 1682004002683, "expires_at": 1703372400000, "icon_url": "http://placekitten.com/200/300", "jump_bpmn_process_id": "00000000-0000-0000-0000-000000000000", "url": "https://www.example.org" }'
Variable Data API
Get Data belonging to a Process Variable
Some process variables can contain files. You can download the contents of these files via the API.
curl "https://app-stable.loyjoy.com/api/variable/data/<ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
--output test.file