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
}