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
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 for GPT knowledge modules
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. If you want to upload a large number of files programmatically, there exists an examplary script.
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"
List All Sources Uploaded as JSON
Returns a JSON list of all knowledge sources of kind Upload in the tenant, i.e. files that have been uploaded as sources. Excludes knowledge sources with other kinds, such as URL.
curl -X GET "https://app-stable.loyjoy.com/api/sources/upload" \
-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/<SOURCE_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/<SOURCE_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Delete All Sources
Deletes all sources in the tenant.
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.
Delete All Sources Uploads
Deletes all sources with kind Upload in the tenant, i.e. all files uploaded as sources.
This will permanently delete all sources with kind Upload in the tenant.
curl -X DELETE "https://app-stable.loyjoy.com/api/sources/upload" \
-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/upload 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, DOCX, HTML, MD, PDF, PPTX, TXT, XLSX 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" }'
Folder Parameter
You can also optionally add a folder name to the upload.
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", "folder": "name" }'
Post a Source Upload
Posts a source file into the tenant. Comparable to uploading a source file in LoyJoy Manager. Valid content types are text/csv, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/html, application/pdf, application/vnd.openxmlformats-officedocument.presentationml.presentation, 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'
URL Parameter
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'
When using curl for uploading a file, do not remove the @ before the file name, or the file upload will fail.
Folder Parameter
Optionally, you can also add a folder name to the upload. The added folder parameter must be URL encoded.
curl -X POST "https://app-stable.loyjoy.com/api/sources/upload?folder=name" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
--form 'file=@sample.pdf'
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/<VARIABLE_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
--output test.file
Products API
These endpoints provide read and write access to products used by database connectors in the Product Feed Module. They allow you to programmatically provide information about your products and store, retrieve, or delete them.
List All Products as JSON
Returns a JSON list of all products in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/products" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Get a Product as JSON
Returns a JSON representation of the product in the tenant.
curl -X GET "https://app-stable.loyjoy.com/api/products/<PRODUCT_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>"
-H "Content-Type: application/json"
Delete a Product
Deletes the product in the tenant.
curl -X DELETE "https://app-stable.loyjoy.com/api/products/<PRODUCT_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Delete All Products
Delete all products in the tenant.
This will permanently delete all products in the tenant.
curl -X DELETE "https://app-stable.loyjoy.com/api/products" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Post a Product
Posts a JSON representation of a product into the tenant.
curl -X POST "https://app-stable.loyjoy.com/api/products" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"title": "Some Product",
"locale": "en",
"description": "Some Product description",
"header": "Some header",
"price": "price",
"image_url": "https://example.com/some_image.png",
"url": "https://example.com/some_product",
....
}'
Note that the fields title and locale are mandatory and must be present in the JSON. All other fields are optional and can enhance the chat experience of your customers. Further, you can set custom fields on your own by providing key-value pairs in the JSON. These fields are stored along the other fields on the first level. This enables using efficient SQL-Queries and utilize your own schema to filter your products in the chat. For example, when using a category field of your product, send the following JSON:
{
"category": "my_category",
"title": "Some Product",
"locale": "en"
}
Then you can filter your products with SQL.
SELECT * FROM products WHERE category = 'my_category';
Upsert a Product
As an alternative to posting a product you can also upsert a product. This means that the product will be updated if it already exists, or created if it does not exist.
curl -X POST "https://app-stable.loyjoy.com/api/products/upsert" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"id": "4566be0c-1ab6-4e63-98c7-d8ad9695e11f",
"title": "Some Product",
"locale": "en",
"description": "Some Product description",
"header": "Some header",
"price": "price",
"image_url": "https://example.com/some_image.png",
"url": "https://example.com/some_product",
....
}'
Upsert a Product by reference_id
As an alternative to posting a product you can also upsert a product by reference_id. This means that the product will be updated if a product already exists with a given reference_id, or created if it does not exist. A reference_id may be an id from your own system.
curl -X POST "https://app-stable.loyjoy.com/api/products/upsert_by_reference_id" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"reference_id": "some_reference_id_123",
"title": "Some Product",
"locale": "en",
"description": "Some Product description",
"header": "Some header",
"price": "price",
"image_url": "https://example.com/some_image.png",
"url": "https://example.com/some_product",
....
}'