Automated reasoning
ZBrain Builder's automated reasoning API empowers users to build intelligent, logic-driven systems by enabling seamless rule extraction, variable management, and dynamic reasoning based on structured knowledge bases. Designed for enterprise-grade AI solutions, this robust API suite simplifies the entire reasoning lifecycle, from importing knowledge bases and extracting logical rules and variables to querying them in real time and managing custom additions. With endpoints tailored for customization, testing, historical tracking, and cost estimation, users gain full control over how their applications interact with rule-based engines and structured datasets.
This documentation offers detailed descriptions of each endpoint, including their functionality, required parameters, request/response structures, and best practices to help you optimize implementation and performance. From dynamic variable extraction to logical inference execution, this API serves as a foundational component for building reliable AI systems rooted in consistent, explainable knowledge.
Base URLs
ZBrain Import Microservice:
https://app.zbrain.ai:3003/api
ZBrain Content Microservice:
https://app.zbrain.ai:3000/api
Authentication
To interact with the automated reasoning API, you must authenticate all requests. Each API call requires the inclusion of the proper authentication credentials, typically in the form of an authentication token or API key, which will be included in the request headers or query parameters.
To interact with the automated reasoning API, authentication is required for all API endpoints. Requests must include the relevant authentication parameters to ensure secure access.
Endpoints overview
1. Trigger automated reasoning
This endpoint initiates the automated reasoning process by extracting logical rules and variables from an imported knowledge base.
Endpoint:
/automated-reasoning
Method: POST
Service: zbrain-import-microservice
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Request body:
{
"model": "gpt-4o",
"prompt": "You are a highly intelligent assistant tasked with extracting structured information from documents. Your goal is to identify and organize variables present in the provided document into a specific format. Respond only with the JSON object and nothing else, so I can directly parse the answer into an object. Use the following instructions to structure your response:\n\nVariables:\n\nIdentify all variables in the document.\n\nFor each variable, extract:\n\nvariable: The name of the variable in camelCase.\n\ndataType: The datatype of the variable.\n\ndescription: A clear explanation of what the variable represents.\n\nReturn all variables as an array of objects.\n\nOutput Format:\n\nVariables: An array of objects, with each object containing variable, type, and description.\n\nExample Output:\n\n{\n \"variables\": [\n {\n \"variable\": \"leaveOfAbsence\",\n \"dataType\": \"int\",\n \"description\": \"A type of leave where an employee is permitted to be absent from work for specific reasons.\"\n },\n {\n \"variable\": \"paidLeave\",\n \"dataType\": \"str\",\n \"description\": \"A type of leave where the employee continues to receive their salary while on leave.\"\n }\n ]\n }\n\nPlease use this format to respond to user inputs and extract the necessary data from any given document.",
"knowledgeBaseId": "your-kb-id"
}
Sample response:
{
"responseData": "Knowledge base automated reasoning completed successfully",
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
2. Retrieve knowledge base variables
Retrieve the list of variables extracted from a knowledge base. These variables are key to logical inferences and are used in dynamic reasoning processes.
Endpoint:
/kb-variables/:id
Method: GET
Service: zbrain-import-microservice
Required parameters:
Replace
:id
in the URL with the specific knowledge base ID.
Optional query parameters:
sortingKey
: The field by which to sort the results (e.g., variable).sortingOrder
: Order of sorting, either asc (ascending) or desc (descending).
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Sample response:
{
"responseData": [
{
"variable": "app",
"dataType": "object",
"description": "An instance of the Express application...",
"isActive": true,
"isDeleted": false,
"addedOn": 1733990212034,
"type": "AUTO",
"importId": "67597e610d96b90024d22327"
}
],
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
3. Retrieve knowledge base rules
Fetch the logical rules that were extracted from a knowledge base. These rules are essential for applying logical reasoning and decision-making in AI applications.
Endpoint:
/kb-rules/:id
Method: GET
Service: zbrain-import-microservice
Required parameters:
Replace
:id
in the URL with the specific knowledge base ID.
Optional query parameters:
sortingKey
: The field to sort by (e.g., rule).sortingOrder
: Sorting order, asc (ascending) or desc (descending).
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Sample response:
{
"responseData": [
{
"rule": "The first index of a sequence is zero...",
"isActive": true,
"isDeleted": false,
"addedOn": 1733990219374,
"type": "AUTO",
"importId": "67597e610d96b90024d22326"
}
],
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
4. Add custom rules or variables
Add new custom rules or variables to a knowledge base. This helps extend or modify the reasoning process by integrating user-defined logic.
Endpoint:
/add-custom-rules-or-variables
Method: POST
Service: zbrain-import-microservice
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Request body for adding a variable:
{
"knowledgeBaseId": "your-kb-id",
"input": {
"variable": "variableName",
"dataType": "dataType",
"description": "variable description"
}
}
Request body for adding a rule:
{
"knowledgeBaseId": "your-kb-id",
"input": {
"rule": "rule statement"
}
}
Sample response:
{
"responseData": {
// Knowledge base details with updated custom rules/variables references
},
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
5. Update or delete rules
Modify or remove existing rules in the knowledge base. This is useful for maintaining the accuracy and relevance.
Endpoint:
/rules
Method: PUT
Service: zbrain-import-microservice
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Request body:
{
"knowledgeBaseId": "your-kb-id",
"action": "UPDATE", // or "DELETE"
"rule": "original rule text",
"updateObject": {
"rule": "updated rule text" // required if action is "UPDATE"
},
"kbImportId": "import-id" // optional
}
Sample response:
{
"responseData": "Rules updated successfully",
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
6. Update or delete variables
Update or remove variables within a knowledge base. Changes to variables may be necessary to reflect new insights or data structures.
Endpoint:
/variables
Method: PUT
Service: zbrain-import-microservice
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Request body:
{
"knowledgeBaseId": "your-kb-id",
"action": "UPDATE", // or "DELETE"
"variable": "variableName",
"updateObject": {
// Update fields for action "UPDATE"
"variable": "newVariableName",
"dataType": "newDataType",
"description": "new description"
},
"kbImportId": "import-id" // optional
}
Sample response:
{
"responseData": "Variables updated successfully",
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
7. Run playground query
Execute reasoning queries directly against the knowledge base using the playground. This is useful for testing or prototyping reasoning queries.
Endpoint:
/playground
Method: POST
Service: zbrain-import-microservice
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Request body
{
"knowledgeBaseId": "your-kb-id",
"query": "your query text"
}
Sample response:
{
"responseData": {
"answer": "Comprehensive answer to the query based on the knowledge base...",
"variables": [
{
"variable": "nodeJs",
"dataType": "str",
"description": "A server-side platform built on Google Chrome's JavaScript Engine..."
}
],
"rules": [
{
"rule": "Node.js applications are written in JavaScript..."
}
]
},
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
8. Retrieve playground history
Access the history of queries that were executed in the playground. This allows for the review of past interactions and the refinement of queries.
Endpoint:
/playground-history/:knowledgeBaseId
Method: GET
Service: zbrain-content-microservice
Optional query parameters:
skip
: Number of records to skip (for pagination).limit
: Number of records to return.sortingKey
: Field to sort by (e.g., query).sortingOrder
: Order of sorting (asc/desc).
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Sample response:
{
"responseData": {
"data": [
{
"_id": "675fd454a964291e1c89af62",
"query": "What are the features of Node.js?",
"llmRes": {
"answer": "Node.js is a server-side platform..."
},
"addedOn": 1734333524687
}
],
"total": 1
},
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
9. Estimate automated reasoning cost
Calculate the cost of running automated reasoning on a knowledge base, including prompt and completion credits.
Endpoint:
/estimate-automated-reasoning-cost
Method: GET
Service:
zbrain-import-microservice
Required query parameters:
model
: Model to use for reasoning.knowledgeBaseId
: Unique ID for your specific knowledge base.
Request headers:
"Authorization": "Bearer <API Key>"
"Content-Type": "application/json"
Sample response:
{
"responseData": {
"promptCredit": 4.22977685,
"completionCredit": 4.998959739130435,
"totalCredit": 9.228736589130435,
"usageCost": {
"promptCost": 0.0084595537,
"completionCost": 0.00999791947826087,
"totalCost": 0.01845747317826087
}
},
"message": "Information fetched successfully",
"success": true,
"responseCode": 200
}
Last updated