Installing a Solution via API

⚠️

Beta Version: This API is currently available in beta. Please note that some features may change or be updated after the pilot program.

Step 1. Authentication

All further requests to the Solution Headless API are performed using the end-user token.

Step 2. Get the List of Solutions

Retrieve the list of solutions created by the master account.

Endpoint:

GET /solution/apps

Description: Returns a list of available solutions for the user. Only the latest published versions of solutions are returned in the list.

Step 3. Get Connection Settings for the Solution

Endpoint:

GET /solution/{solution_id}/credentialists

Description: Returns the structure of connection settings—steps and nested steps that need to be filled in to install the solution.

Example request:

GET /solution/{solution_id}/credentialists
Authorization: Bearer YOUR_JWT_TOKEN

If there is nesting:

GET /solution/{solution_id}/credentialists?credentialData[step1]=value1&credentialData[step2]=value2

Step 4. Install the Solution

Endpoint:

POST /solution/{solution_id}/installation

What should be in data (request body):

• credentialData — an object with selected values for each step (and nested step) of the connection settings used in solutions.
• templateIds — an array of template IDs to be installed.
• title — the name of the installation (any string you can use to identify the installation).
• settings — (optional) an object with additional user settings, if provided by your solution.

Forming the credentialData object

• credentialData is an object where the keys are step IDs (step.id), and the values are the selected values for these steps (e.g., account ID, table ID, sheet name, etc.).
• For each step from credentialists, select the required value from the values field.
• If a step contains nested steps, make additional GET requests to /credentialists, adding already selected values to credentialData to reveal the next nesting level.
• Repeat the process until you reach the last nesting level (nested is empty).

Example of forming credentialData with nesting:

1. Received credentialists:
   - step1 (select value1)
   - step2 (select value2, after selection nested step3 appears)
2. Make a request:
   GET /solution/{solution_id}/credentialists?credentialData[step2]=value2
   - step3 (select value3)
3. Final object:
{
  "credentialData": {
    "step1": "value1",
    "step2": "value2",
    "step3": "value3"
  }
}

Forming the templateIds array

• To install a solution, you need to specify which templates will be installed. Each template is associated with one of the "parent" automations that define the automation logic.
• Get the list of available templates for the selected solution using the request:

GET /solution/{solution_id}/templates

• The response will contain an array of template objects. Each template will have its identifier (id), as well as information about the associated parent automation and template parameters.
• Select the required templates for installation (e.g., by name, description, or other parameters).
• Form the templateIds array by including the IDs of the selected templates:

"templateIds": [12345, 67890]

Forming the settings object

• settings — an additional object for passing user settings, if provided by your solution.
• The structure of settings depends on the specific solution and is described in its documentation.
• If the solution supports settings, add this object to the request body:

{
  "credentialData": {
    "step1": "value1",
    "step2": "value2",
    "step3": "value3"
  },
  "templateIds": [12345, 67890],
  "title": "My Solution Installation",
  "settings": {
    "field1": "customValue1",
    "field2": "customValue2"
  }
}

Important: If settings are not required, this object can be omitted.

Example request

curl -X POST 'https://api.albato.com/solution/{solution_id}/installation' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "credentialData": {
      "step1": "value1",
      "step2": "value2",
      "step3": "value3"
    },
    "templateIds": [12345, 67890],
    "title": "My Solution Installation",
    "settings": {
      "field1": "customValue1"
    }
  }'

Step 5. Start the Solution Installation

After installing the solution, you can start the execution of the installation.

Endpoint:

PLAY /solution/installation/{installation_id}

Description: Starts the execution of the installed solution. Usually used after all required parameters and templates have been selected and the installation has been created.

Example request:

curl --location --request PLAY 'https://api.albato.com/solution/installation/{installation_id}' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'

Example response:

{
  "success": true,
  "data": {
    "id": 9208,
    "appId": 20003,
    "status": 1, // 1 = active (started)
    ...
  }
}

Step 6. Pause the Solution Installation

If you need to temporarily pause the execution of the installation, use the PAUSE method.

Endpoint:

PAUSE /solution/installation/{installation_id}

Description: Pauses the execution of the installed solution. After pausing, you can make changes to the field values of the installation.

Example request:

curl --location --request PAUSE 'https://api.albato.com/solution/installation/{installation_id}' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'

Example response:

{
  "success": true,
  "data": {
    "id": 9208,
    "appId": 20003,
    "status": 0, // 0 = paused
    ...
  }
}

Important: You can change field values only for paused solution installations. If the installation is active, first pause it using PAUSE.