Meet the New ecosystem.Ai Resources Hub! 🚀
DocsRuntime & DeploymentAPI Access

Introduction

The ecosystem.Ai runtime exposes APIs that can be used to access your deployed configuration.

  • The /invocations endpoint is used to access the deployment and receive a response based on the configured rules
  • The /response endpoint is used to send record successful interactions generated using the information returned by the /invocations call. This is used for logging and learning.
  • The /refresh endpoint is used to refresh the runtime and reload any data held in memory
  • The /refreshWithOptions endpoint is used to regenerate the Options Store and then refresh the runtime.

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": "{}",
    "in_param": {
        "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.

✏️
Example `/invocations` Response for Spend Personality▷

This is the standard return for the Spend Personality API:

openapi: 3.0.0
info:
  title: Spend Personality API
  description: API that obtains spending personality insights and pushes responses once customer values are returned.
  version: "1.0.0"
servers:
  - url: https://bankruntime2.ecosystem.ai
paths:
  /invocations:
    post:
      summary: Obtain Spend personality
      operationId: getSpendPersonality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                campaign:
                  type: string
                  description: Campaign identifier
                  default: spend_personality
                subcampaign:
                  type: string
                  description: Subcampaign identifier
                  default: spend_personality
                channel:
                  type: string
                  description: Customer interaction channel
                  default: copilot
                customer:
                  type: string
                  description: Customer identifier
                  default: 590
                numberoffers:
                  type: string
                  description: Number of offers to display
                  default: "1"
                userid:
                  type: string
                  description: User ID
                  default: copilot
                params:
                  type: string
                  description: Additional parameters in JSON format
                  default: "{}"
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  cache:
                    type: integer
                    description: Indicates if the response is cached (0 for no, 1 for yes)
                    example: 0
                  datetime:
                    type: string
                    format: date-time
                    description: Timestamp of the response
                    example: "2024-12-20T13:04:43.000774Z"
                  explore:
                    type: integer
                    description: Exploration score (default 0)
                    example: 0
                  final_result:
                    type: array
                    description: Array of final results for spend personality analysis
                    items:
                      type: object
                      properties:
                        result:
                          type: object
                          properties:
                            offer:
                              type: string
                              description: The recommended offer
                              example: "Industrious"
                            score:
                              type: number
                              description: Personality trait score associated with the offer
                              example: 0.4742771310552009
                            final_score:
                              type: number
                              description: Final calculated score
                              example: 0.4742771310552009
                            cost:
                              type: integer
                              description: Cost associated with the recommendation
                              example: 1
                            price:
                              type: integer
                              description: Price of the offer
                              example: 1
                            offer_value:
                              type: integer
                              description: Value of the offer
                              example: 1
                            uuid:
                              type: string
                              description: Unique ID for the recommendation
                              example: "fdfbe8f4-7f99-4315-9614-ca68e6c50b4b"
                            arm_reward:
                              type: number
                              description: Reward score associated with the offer
                              example: 0.4742771310552009
                            modified_offer_score:
                              type: number
                              description: Adjusted score for the offer
                              example: 0.5204656402553511
                            offer_name:
                              type: string
                              description: Name of the offer
                              example: "Industrious"
                        result_full:
                          type: object
                          properties:
                            cost:
                              type: number
                              description: Cost metric
                              example: 1
                            industrious:
                              type: number
                              description: Industrious personality score
                              example: 0.4742771310552009
                            offer_name:
                              type: string
                              description: Name of the offer
                              example: "Industrious"
                            personality:
                              type: string
                              description: Detected personality type
                              example: "Industrious"
                            score:
                              type: number
                              description: Overall personality score
                              example: 0.4742771310552009
                            trait:
                              type: string
                              description: Prominent personality trait detected
                              example: "Extrovert"
                        rank:
                          type: integer
                          description: Rank or priority of this result
                          example: 1
                  id:
                    type: string
                    description: Unique identifier for the analysis type
                    example: spend_personality
                  uuid:
                    type: string
                    description: UUID for the overall response
                    example: "fdfbe8f4-7f99-4315-9614-ca68e6c50b4b"
                  in_params:
                    type: object
                    description: Input parameters for the request
                    example: {}
  /response:
    post:
      summary: Respond to Spend personality when customer lookup happens
      operationId: customerResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  description: Unique identifier for the request
                  example: "fdfbe8f4-7f99-4315-9614-ca68e6c50b4b"
                offers_accepted:
                  type: array
                  description: List of offers accepted by the customer
                  items:
                    type: string
                  example: ["offer1"]
                channel:
                  type: string
                  description: Customer channel type
                  default: chatgpt
      responses:
        "200":
          description: Response confirmation
          content:
            application/json:
              schema:
                type: object
                properties:
                  final_result:
                    type: array
                    description: The final response result from the API
                    items:
                      type: object
 
components:
  schemas:
    SpendPersonalityRequest:
      type: object
      properties:
        campaign:
          type: string
          description: Campaign identifier
          default: spend_personality
        subcampaign:
          type: string
          description: Subcampaign identifier
          default: spend_personality
        channel:
          type: string
          description: Customer interaction channel
          default: copilot
        customer:
          type: string
          description: Customer identifier
          default: 590
        numberoffers:
          type: string
          description: Number of offers to display
          default: "1"
        userid:
          type: string
          description: User ID
          default: copilot
        params:
          type: string
          description: Additional parameters in JSON format
          default: "{}"
    SpendPersonalityResponse:
      type: object
      properties:
        cache:
          type: integer
          description: Indicates if the response is cached (0 for no, 1 for yes)
          example: 0
        datetime:
          type: string
          description: Timestamp of the response
          example: "2024-12-20T13:04:43.000774Z"

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}}

✏️
Example Flattened `/invocations` Response for Spend Personality▷

This is the return for the Spend Personality API when called with {"in_param": {"flatten_json": true}}:

openapi: 3.0.0
info:
  title: Spend Personality API
  description: API that obtains spending personality insights and pushes responses once customer values are returned.
  version: "1.0.0"
servers:
  - url: https://bankruntime2.ecosystem.ai
paths:
  /invocations:
    post:
      summary: Obtain Spend personality
      operationId: getSpendPersonality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                campaign:
                  type: string
                  description: Campaign identifier
                  default: spend_personality
                subcampaign:
                  type: string
                  description: Subcampaign identifier
                  default: spend_personality
                channel:
                  type: string
                  description: Customer interaction channel
                  default: copilot
                customer:
                  type: string
                  description: Customer identifier
                  default: 590
                numberoffers:
                  type: string
                  description: Number of offers to display
                  default: "1"
                userid:
                  type: string
                  description: User ID
                  default: copilot
                params:
                  type: string
                  description: Additional parameters in JSON format
                  default: "{}"
      responses:
        "200":
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  final_result_0_result_full_industrious:
                    type: number
                    description: Industrious personality score
                    example: 0.4742771310552009
                  final_result_0_result_full_transaction_count:
                    type: integer
                    description: Total transaction count
                    example: 2663
                  final_result_0_result_score:
                    type: number
                    description: Personality trait score associated with the offer
                    example: 0.4742771310552009
                  final_result_0_result_offer_name:
                    type: string
                    description: Name of the offer
                    example: "Industrious"
                  final_result_0_result_full_uuid:
                    type: string
                    description: Unique ID associated with the personality result
                    example: "e98aeb34-786d-453f-8798-a03145a34e2f"
                  uuid:
                    type: string
                    description: Primary UUID of the response
                    example: "e98aeb34-786d-453f-8798-a03145a34e2f"
                  final_result_0_result_full_offer:
                    type: string
                    description: The recommended offer
                    example: "Industrious"
                  final_result_0_result_cost:
                    type: integer
                    description: Cost associated with the recommendation
                    example: 1
                  datetime:
                    type: string
                    format: date-time
                    description: Timestamp of the response
                    example: "2024-12-20T18:08:52.000565Z"
                  final_result_0_result_full_modified_offer_score:
                    type: number
                    description: Adjusted score for the offer
                    example: 0.5204656402553511
                  final_result_0_result_full_personality:
                    type: string
                    description: Detected personality type
                    example: "Industrious"
                  final_result_0_result_full_extrovert:
                    type: number
                    description: Extrovert score for the customer
                    example: 0.5204656402553511
                  final_result_0_result_full_offer_details_1:
                    type: integer
                    description: Offer detail, key `1`
                    example: 1
                  final_result_0_result_full_offer_details_0:
                    type: integer
                    description: Offer detail, key `0`
                    example: 0
                  final_result_0_result_full_trait:
                    type: string
                    description: Prominent personality trait detected
                    example: "Extrovert"
                  final_result_0_result_full_offer_id:
                    type: string
                    description: Identifier for the offer
                    example: "Industrious"
                  final_result_0_result_full_price:
                    type: integer
                    description: Price of the offer
                    example: 1
                  id:
                    type: string
                    description: Unique identifier for the analysis type
                    example: spend_personality
                  final_result_0_result_final_score:
                    type: number
                    description: Final calculated score
                    example: 0.4742771310552009
                  final_result_0_result_full_offer_value:
                    type: integer
                    description: Value of the offer
                    example: 1
                  final_result_0_result_full_intentional:
                    type: number
                    description: Intentional score for the customer
                    example: 0.09500563274502441
                  final_result_0_result_price:
                    type: integer
                    description: Price of the offer
                    example: 1
                  in_params_flatten_json:
                    type: boolean
                    description: Indicates if the input parameters were flattened
                    example: true
                  cache:
                    type: integer
                    description: Indicates if the response is cached (0 for no, 1 for yes)
                    example: 0
                  explore:
                    type: integer
                    description: Exploration score (default 0)
                    example: 0
                  final_result_0_result_full_offer_name:
                    type: string
                    description: Name of the offer
                    example: "Industrious"
                  final_result_0_result_uuid:
                    type: string
                    description: Unique ID for the recommendation
                    example: "e98aeb34-786d-453f-8798-a03145a34e2f"
                  final_result_0_result_modified_offer_score:
                    type: number
                    description: Adjusted score for the offer
                    example: 0.5204656402553511
                  final_result_0_result_full_enthusiastic:
                    type: number
                    description: Enthusiastic personality score
                    example: 0.06759294029290275
                  final_result_0_result_full_score:
                    type: number
                    description: Overall personality score
                    example: 0.4742771310552009
                  final_result_0_rank:
                    type: integer
                    description: Rank or priority of this result
                    example: 1
                  final_result_0_result_full_introvert:
                    type: number
                    description: Introvert score for the customer
                    example: 0.2377018400300413
                  final_result_0_result_full_experiential:
                    type: number
                    description: Experiential personality score
                    example: 0.12129177619226436
                  final_result_0_result_full_cost:
                    type: integer
                    description: Cost metric
                    example: 1
                  final_result_0_result_offer:
                    type: string
                    description: The recommended offer
                    example: "Industrious"
                  final_result_0_result_offer_value:
                    type: integer
                    description: Value of the offer
                    example: 1
                  final_result_0_result_arm_reward:
                    type: number
                    description: Reward score associated with the offer
                    example: 0.4742771310552009

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 to generateDefaultOptions, which will generate the Options Store from scratch, or generateUpdatedOptions, which will keep existing options in the Options Store and check the setup feature store for any new options that should be added
  • cassandra_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 to mongo_offer_database.mongo_offer_collection in the MongoDB database.
  • mongo_offer_database: This field specifies the name of the MongoDB database that contains the offers
  • mongo_offer_collection: This field specifies the name of the MongoDB collection that contains the offers
  • mongo_setup_database: This field specifies the name of the MongoDB database that contains the Set Up Feature Store
  • mongo_setup_collection: This field specifies the name of the MongoDB collection that contains the Set Up Feature Store
  • contextual_variable_one_name: This field specifies the name of the first contextual variable
  • contextual_variable_one_values: This field specifies the values for the first contextual variable
  • contextual_variable_two_name: This field specifies the name of the second contextual variable
  • contextual_variable_two_values: This field specifies the values for the second contextual variable
  • offer_name_column: This field specifies the name of the column in mongo_offer_database.mongo_offer_collection that 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.

🔥
Note

The /refreshWithOptions API will reset the entire Options Store to its default values if type is set to the default value, i.e. until the Options Store is next updated by the ecosytem.Ai runtime, the history contained in the logging collections will be ignored.

Environment VariablesLogging & Reporting