Skip to main content

REST API

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

caution

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.

Processes API​

List All Processes as JSON​

ownereditorprocesses_editorprocesses_viewer

Returns a JSON list of all processes in the tenant.

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

Get a Process as JSON​

ownereditorprocesses_editorprocesses_viewer

Returns a JSON representation of the process in the tenant.

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

Get a Process as XML​

ownereditorprocesses_editorprocesses_viewer

Returns a XML representation of the process 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/processes/xml/<PROCESS_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/xml"

Start a Process​

ownereditor

Starts a process programmatically. This call optionally can ingest variables, and then returns the resulting variables. The process instance will halt if the process expects user input. E.g. if the process 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/processes/start/<PROCESS_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "variables": { "some_var": { "value": "some_value" } } }'

Home Views API​

List All Views as JSON​

ownereditorprocesses_editorprocesses_viewer

Returns a JSON list of all views in the tenant.

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

Get a Home View as JSON​

ownereditorprocesses_editorprocesses_viewer

Returns a JSON representation of the view in the tenant.

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

Get a Home View as XML​

ownereditorprocesses_editorprocesses_viewer

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/views/xml/<VIEW_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/xml"

Chunks API​

Search for Chunks​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

Searches for up to 100 chunks by a given search term.

curl -X POST "https://app-stable.loyjoy.com/api/chunks/search" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "query": "What is LoyJoy?" }'
curl -X POST "https://app-stable.loyjoy.com/api/chunks/search" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "query": "What is LoyJoy?", "folders": ["folder1"], "max_chunks": 10 }'

Catalogs API for Knowledge database​

List All Catalogs as JSON​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

Returns a JSON list of all catalogs in the tenant.

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

Get a Catalog as JSON​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

Returns a JSON representation of the catalog in the tenant.

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

Get a Catalog as XML​

ownereditorknowledge_exporter

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/catalogs/xml/<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/xml"

Delete a Catalog​

ownereditorknowledge_editor

Deletes the catalog in the tenant.

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

Post a Catalog​

ownereditorknowledge_editor

Posts a JSON representation of a catalog into the tenant.

curl -X POST "https://app-stable.loyjoy.com/api/catalogs" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "name": "Some Catalog" }'

Articles API​

List All Articles of a Catalog as JSON​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

Returns a JSON list of all articles of a knowledge catalog in the tenant.

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

Get an Article of a Catalog as JSON​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

Returns a JSON representation of the article of a catalog in the tenant.

curl -X GET "https://app-stable.loyjoy.com/api/articles/<ARTICLE_ID>?catalog_id=<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Delete an Article of a Catalog​

ownereditorknowledge_editor

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/articles/<ARTICLE_ID>?catalog_id=<CATALOG_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Post an Article of a Catalog as JSON​

ownereditorknowledge_editor

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/articles?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" }'

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. 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​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

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​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

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​

ownereditorknowledge_editorknowledge_exporterknowledge_viewer

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​

ownereditorknowledge_editor

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​

ownereditorknowledge_editor

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.

Delete All Sources Uploads​

ownereditorknowledge_editor

Deletes all sources with kind Upload in the tenant, i.e. all files uploaded as sources.

danger

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​

ownereditorknowledge_editor

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​

ownereditorknowledge_editor

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'
tip

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'

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.

Postman Collection

List All Products as JSON​

ownereditorproducts_editorproducts_exporterproducts_viewer

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​

ownereditorproducts_editorproducts_exporterproducts_viewer

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​

ownereditorproducts_editor

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​

ownereditorproducts_editor

Delete all products in the tenant.

danger

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​

ownereditorproducts_editor

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 agent 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​

ownereditorproducts_editor

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​

ownereditorproducts_editor

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

Participation Winners API​

Get All Participation Winners by Giveaway ID as JSON​

ownereditordata_exporter

Returns a JSON list of all participation winners of a giveaway in the tenant.

curl -X GET "https://app-stable.loyjoy.com/api/participation_winners/by_giveaway?giveaway_id=<GIVEAWAY_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Create Participation Winners as JSON​

ownereditordata_editor

Creates participation winners for a giveaway in the tenant. The amount is the number of winners to be created. The bpmn_process_id is the ID of the process that contains the giveaway. The giveaway_id is the ID of the giveaway for which the winners are created. There need to exist enough participations in the giveaway to create the winners.

curl -X POST "https://app-stable.loyjoy.com/api/participation_winners" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "amount": <AMOUNT>, "bpmn_process_id": "00000000-0000-0000-0000-000000000000", "giveaway_id": "00000000-0000-0000-0000-000000000000" }'

Variables API​

Get All Variables as JSON​

data_exporter

Returns a JSON list of all variables in the tenant.

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

Get All Variables by Process ID as JSON​

data_exporter

Returns a JSON list of all variables of a process in the tenant.

curl -X GET "https://app-stable.loyjoy.com/api/variables/by_bpmn_process?bpmn_process_id=<PROCESS_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"

Post a Variable as JSON​

ownereditordata_editor

Posts a JSON representation of a variable into the tenant.

curl -X POST "https://app-stable.loyjoy.com/api/variables" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "key": "some_key", "value": "some_value", "scope": "process", "bpmn_process_id": "00000000-0000-0000-0000-000000000000", "device_id": "00000000-0000-0000-0000-000000000000", "email": "user@example.org", "expires_at": 1703372400000, "process_instance_id": "00000000-0000-0000-0000-000000000000" }'

Get Data belonging to a Variable​

ownereditordata_editordata_exporterdata_viewer

A process variable can contain a file, e.g. in case of a file upload questionnaire question. You can download the content of such a file via the variable data API.

curl "https://app-stable.loyjoy.com/api/variables/data/<VARIABLE_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
--output test.file

Web Notifications API​

Post a Web Notification as JSON​

ownereditordata_editor

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