Introduction
The ecosystem.Ai runtime exposes APIs that can be used to access and manage your deployed configuration.
- The
/invocationsendpoint is used to access the deployment and receive a response based on the configured rules - The
/responseendpoint is used to send record successful interactions generated using the information returned by the/invocationscall. This is used for logging and learning. - The
/refreshendpoint is used to refresh the runtime and reload any data held in memory - The
/refreshWithOptionsendpoint is used to regenerate the Options Store and then refresh the runtime. - The
/learningendpoint is used to manually trigger the learning process for a Dynamic Interaction deployment. This process is normally triggered based on the MONITORING_DELAY environment variable. Manually triggering the learning is useful for testing and simulation purposes - The
/updateCassandraConfigendpoint is used to update the contents of theconffile that is use the detail the Cassandra connection information, if required.
Custom APIs can also be exposed.
/invocations
You can access your deployed runtime at the configured URL using the /invocations endpoint. The API is a RESTfull API that accepts POST requests.
curl -X POST http://ecosystem-runtime:8091/invocations \
-H "Content-Type: application/json" \
-d '{
"campaign": "spending_personality",
"subcampaign": "openai",
"channel": "chatgpt",
"customer": "1234",
"numberoffers": "1",
"userid": "openai",
"params": "{}"
}'Here is another example payload with a in_param set that can later be used in the model.
{
"campaign": "spending_personality",
"subcampaign": "openai",
"channel": "chatgpt",
"customer": "1234",
"numberoffers": "1",
"userid": "openai",
"params": {
"airtime_balance": 200,
"airtime_advance_limit": 30,
"api_payment_method": "p"
}
}Modules have different endpoints and payloads. The following is an example of the Spend Personality /invocations API in OpenAPI 3.0Ā standard.
If you do not want the API to return an array or document in document JSON objects then use the flatten option. This is especially useful for UI and other technologies that have difficulty with processing nested JSON objects. The example uses the in_param to force a flattened response: {"in_param": {"flatten_json": true}}
URL Encoding is required for the in_param field.
{
"campaign": "justforyou_nb",
"subcampaign": "justforyou_nb",
"channel": "app",
"customer": "1846573d-ac20-45df-a9f0-2fb14da6e7d1",
"userid": "ecosystem",
"numberoffers": "3",
"params": "%22%7B%5C%22airtime_balance%5C%22:%20200,%20%5C%22airtime_advance_limit%5C%22:%2030,%20%5C%22api_payment_method%5C%22:%20%5C%22p%5C%22%7D%22"
}/response
Use the /response API to send the selected uuid from the /invocations API in order to record a successful interaction. The /response API can be called in two ways. Firstly, as shown in the example, by populating the request body with a JSON objec that contains the uuid and offers_accepted fields. The uuid is the unique identifier returned by the /invocations API, and offers_accepted is an array of offers that were accepted by the customer. The channel_name is also required to indicate the channel through which the interaction occurred.
curl -X 'POST' \
'http://ecosystem-runtime:8091/response' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"uuid": "dcb54a23-0737-4768-845d-48162598c0f7", "offers_accepted": [{"offer_name": "OFFER_A"}], "channel_name": "app"}'Secondly, if all offers from the /invocations API were accepted, you can use the response from the /invocations API as the request body for the /response API. This is shown in the example below.
curl -X 'POST' \
'http://localhost:8091/response' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"cache": 0,
"datetime": "2025-06-02T11:32:56.000214+02:00",
"explore": 0,
"final_result": [
{
"result": {
"contextual_variable_two": "Grade12",
"cost": 0,
"learning_reward": 1,
"contextual_variable_one": "Industrious",
"uuid": "9fcfc54a-5282-4a1c-a6fc-aabc0b324456",
"modified_offer_score": 0,
"offer_name": "Rewards Booster",
"offer": "Rewards Booster",
"score": 0.8550094429534856,
"final_score": 0.8550094429534856,
"price": 0,
"offer_value": 0,
"arm_reward": 0.8550094429534856
},
"result_full": {
"expected_takeup": -1,
"contextual_variable_two": "Grade12",
"cost": 0,
"explore": 0,
"epsilon_nominated": 1,
"learning_reward": 1,
"contextual_variable_one": "Industrious",
"offer_name_desc": "Recommended offer is Rewards Booster",
"weighting": 1,
"uuid": "9fcfc54a-5282-4a1c-a6fc-aabc0b324456",
"offer_name": "Rewards Booster",
"modified_offer_score": 0,
"offer": "Rewards Booster",
"p": 0.8550094429534856,
"score": 0.8550094429534856,
"final_score": 0.8550094429534856,
"propensity": 0,
"price": 0,
"alpha": 1,
"offer_value": 0,
"beta": 1,
"arm_reward": 0.8550094429534856
},
"rank": 1
}
],
"id": "offer_recommend_dynamic",
"uuid": "9fcfc54a-5282-4a1c-a6fc-aabc0b324456",
"in_params": {
"contextual_variable_two": "Grade12",
"contextual_variable_one": "Industrious"
}
}'/refresh
The /refresh API is called without a request body and will clear and reload the scoring and data structures in the runtimes memory and reconnect to all configured data sources.
curl -X 'GET' \
'http://localhost:8091/refresh' \
-H 'accept: */*'/refreshWithOptions
The /refreshWithOptions API can be used when the runtime is configured to use an Options Store. This API will generate the Options Store from the setup feature store and then refresh the runtime. In order to do this the runtime calls the /updateClientPulseResponder API exposed by the ecosystem.Ai server. You will need to generate a key to connect to the ecosystem.Ai server. This can be done using the Workbench. The following example shows how to call the /refreshWithOptions API using curl. The url and token fields are required in the request body. url is the URL of the ecosystem.Ai server and token is the key generated using the Workbench. You can also include a campaign field in the request body to specify the name of the Dynamic Interaction configuration for which the Options Store should be generated. If no campaign is specified, the name of the Deployment will be assumed to be same as the name of the Dynamic Interaction configuration.
curl -X 'POST' \
'http://localhost:8091/refreshWithOptions' \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{
"url":"http://ecosystem-server:3001/api"
"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbkBlY29zeXN0ZW0uYWkiLCJ0eXBlIjoiQVBJX0tFWSIsInNlcnZlcklkIjoiaHR0cDovLzEyNy4wLjAuMSIsImlzcyI6Imh0dHA6Ly8xMjcuMC4wLjEiLCJpYXQiOjE3NDUxNjM4NDEsImV4cCI6MTc0NTI1MDI0MX0.hvb7N0UeEjINAf1nGyCQviug-bC-SVf1LzwFMZk0oIY"
}'There are a number of additional optional fields the can be included in the request body that will change the behavior of the /refreshWithOptions API:
type: This field can be set togenerateDefaultOptions, which will generate the Options Store from scratch, orgenerateUpdatedOptions, which will keep existing options in the Options Store and check the setup feature store for any new options that should be addedcassandra_offer_query: This field specifies a Cassandra query that will be run to retrieve a table of offers to be used to update the Set Up Feature Store, this would generally be the Offer Matrix. The response from the query will be written tomongo_offer_database.mongo_offer_collectionin the MongoDB database.mongo_offer_database: This field specifies the name of the MongoDB database that contains the offersmongo_offer_collection: This field specifies the name of the MongoDB collection that contains the offersmongo_setup_database: This field specifies the name of the MongoDB database that contains the Set Up Feature Storemongo_setup_collection: This field specifies the name of the MongoDB collection that contains the Set Up Feature Storecontextual_variable_one_name: This field specifies the name of the first contextual variablecontextual_variable_one_values: This field specifies the values for the first contextual variablecontextual_variable_two_name: This field specifies the name of the second contextual variablecontextual_variable_two_values: This field specifies the values for the second contextual variableoffer_name_column: This field specifies the name of the column inmongo_offer_database.mongo_offer_collectionthat contains the offer names
If mongo_offer_database, mongo_offer_collection, mongo_setup_database, mongo_setup_collection, contextual_variable_one_name, contextual_variable_one_values, contextual_variable_two_name, contextual_variable_two_values and offer_name_column are specified then the Set Up Feature Store will be updated before the Options Store is generated.
If cassandra_offer_query is specified then mongo_offer_database.mongo_offer_collection will be updated from Cassandra before the Set Up Feature Store is updated.
/learning
The /learning API is called without a request body and will trigger the Dynamic Interaction learning process.
curl -X 'GET' \
'http://localhost:8091/learning' \
-H 'accept: */*'/updateCassandraConfig
The /updateCassandraConfig API update the contents of the conf file which contains the details of the Cassandra connection to be used by the runtime. The /refresh API should be called in order for the new connection details to take effect.
curl -X 'POST' \
'http://localhost:8091/updateCassandraConfig' \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '# ECOSYSTEM
datastax-java-driver {
basic.session-name = my_session
basic.session-keyspace = my_keyspace
basic.config-reload-interval = 5 minutes
basic.request {
timeout = 5 seconds
consistency = LOCAL_ONE
page-size = 5000
serial-consistency = SERIAL
default-idempotence = false
}
basic.load-balancing-policy {
class = DefaultLoadBalancingPolicy
local-datacenter = datacenter1
}
'