Execution API Reference

The Execution API should be used by third party applications to:

Start execution of a published module, thereby creating a session in the process
Pass start parameters to a published module
Query the current status of a published module’s session

This API can currently not be used to:

Return values

Enable access of a module via API Key

Before you’re able to use the Execution API to trigger the execution of a published module, the publishing settings of the module must be changed. In the publishing settings, select Only accessible via an API key under Access Settings

Enabling access via API key in the publishing settings

Define Start parameters

Start parameters define data that will be passed to the module when it is executed. They can be defined by clicking on the “Start” node of your module in the BRYTER editor. Start parameters should only be used when the API is being used to pass data into the module.

Defining a start parameter in the “Start” node

Start parameters are configured as follows:

Name

The name of the start parameter when referenced in the module editor (e.g. Employment Start Date). The parameter can then be referenced in the module by using the @ key followed by the name of the parameter. Please note, this is not the name that should be used in the API call.

Type

The type of value that defines the start parameter (e.g. Date or Number)

Available start parameter types:

Text
Date (YYYY-MM-DD)
Number
Email Address

API parameter name

The name of the parameter to be used when calling the API endpoint (e.g. employment_start_date)

Example Execution API Call: Start execution of a published module

Example values NiAMlNvpsDkMgmYpCPzBL8PfGFXGO1XE4Xko3bkW2bE: API Key

oITwNKIrRdS0A0TFVPP54g: Published Module Id

C0jz_2J6RmOLoB8DyXPs9Q: Session Id

Without start parameters

Request

POST /api/execution/PUBLISHED_MODULE_ID/sessions //REPLACE PUBLISHED_MODULE_ID with the ID of the ID of the published module you would like to execute 
Authorization: Bearer API_KEY //REPLACE API_KEY with the published module’s API key
Content-Type: application/json

With start parameters

If applicable, start parameters should be inserted within the body of the API call.

The following example executes a module that accepts employee data:

Request

POST /api/execution/PUBLISHED_MODULE_ID/sessions //REPLACE PUBLISHED_MODULE_ID with the ID of the ID of the published module you would like to execute 
Authorization: Bearer API_KEY //REPLACE API_KEY with the published module’s API key
Content-Type: application/json

{ 
    "data": {
        "startParameters": {
						"employee_name": "John Doe",
						"employee_email": "john.doe@example.com",
						"employment_start_date": "2021-09-09"
        }
    }
}

In the example above, the module accepts the following start parameters:

employee_name, a text variable that is passed the value of “John Doe”

employee_email, an email variable that is passed the value of “john.doe@example.com”

employee_start_date, a date variable that is passed the value of “2021-09-09”

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
      "sessionId":  "SESSION_ID" //SESSION_ID will be automatically replaced with the ID of the session that has been initiated
    }, 
    "links": {
        "self": "/api/execution/PUBLISHED_MODULE_ID/sessions/SESSION_ID",
        "browser": "https://app.bryter.test/s/PUBLISHED_MODULE_ID/sessions/SESSION_ID"
    }
}

Query the current status of a session

Once you receive a response from the Module Execution API call, you can run another API call to check the progress of the session initiated by the Module Execution API call. This allows you to monitor the status of the session and check if any errors have occurred.

Example Session Query API Call

Request

GET /api/execution/MODULE_ID/sessions/SESSION_ID  //REPLACE PUBLISHED_MODULE_ID WITH THE ID OF THE MODULE EXECUTED BY THE MODULE EXECUTION API AND REPLACE SESSION_ID WITH THE ID OF THE SESSION RETURNED BY THE RESPONSE FOT HE MODULE EXECUTION API CALL
Authorization: Bearer API_KEY  //REPLACE API_KEY with the published module’s API key
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
      "state": "created"
    }, 
    "links": {
        "self": "/api/execution//PUBLISHED_MODULE_ID/sessions/SESSION_ID",
        "browser": "https://app.bryter.test/PUBLISHED_MODULE_ID/sessions/SESSION_ID"
    }
}

The response will contain the current state or status of the session.

Possible Session States:

created: Session has been created but processing didn't start yet
running: Engine is currently processing the session
waiting_for_input: Engine is waiting for user input
fatal_errored: There was a fatal error in the module execution that can't be recovered
completed: The session completed successfully
unknown: The session pre-dates the module execution API

← Previous

Getting Started

Case DB API Reference