Skip to main content

REST API

LoyJoy offers a REST API for programmatically accessing process definitions, home views, catalogs, articles, notifications and variables.

caution

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" }'

Sources API

These endpoints provide read and write access to sources used by the GPT knowledge module. They allow you to add sources such as websites or files to the knowledge base, retrieve them, and delete them. Sources can be added via publicly available URLs or by uploading files.

Additionally, the API also allows you to update the sources according to a schedule or on demand. To achieve this, you can simply delete some or all of your sources and then re-add them. This will trigger a re-crawl of the source.

List All Sources as JSON

Returns a JSON list of all knowledge sources in the tenant.

curl -X GET "https://app-stable.loyjoy.com/api/sources" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Get a Source as JSON

Returns a JSON representation of the source in the tenant.

curl -X GET "https://app-stable.loyjoy.com/api/sources/<ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>"
-H "Content-Type: application/json"

Delete a Source

Deletes the source in the tenant.

curl -X DELETE "https://app-stable.loyjoy.com/api/sources/<ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Delete All Sources

Deletes all sources in the tenant.

danger

This will permanently delete all sources in the tenant.

curl -X DELETE "https://app-stable.loyjoy.com/api/sources" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Each source takes approximately 500ms to be deleted. If you want to delete several hundred or thousand of sources, the API call might time out on the load balancer. However, in the background the deletion should continue. In case of a timeout, please do not retry directly after timeout, but instead wait for several minutes until retry. You can check the status of the deletion by calling the GET /sources endpoint and counting the resulting items.

Post a Source

Posts a JSON representation of a source into the tenant. The field type may have one of the values CSV, HTML, PDF or ZIP.

curl -X POST "https://app-stable.loyjoy.com/api/sources" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "type": "HTML", "url": "https://www.example.org/example.html" }'

Upload a Source File

Posts a file source into the tenant. Comparable to uploading a source file in LoyJoy Manager. Valid content types are text/csv, text/html, application/pdf, application/xml and application/zip.

curl -X POST "https://app-stable.loyjoy.com/api/sources/upload" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
--form 'file=@sample.pdf'

Optionally, you can also add a URL to be referenced when displaying the source in the chat. The added URL parameter must be URL encoded.

curl -X POST "https://app-stable.loyjoy.com/api/sources/upload?url=https%3A%2F%2Fwww.example.org%2Fsample.pdf" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
--form 'file=@sample.pdf'
tip

When using curl for uploading a file, do not remove the @ before the file name, or the file upload will fail.

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.

caution

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.

caution

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