> For the complete documentation index, see [llms.txt](https://docs.decisionrules.io/doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decisionrules.io/doc/api/rule-solver-api/rule-solver-api.md). # Rule Solver API AERO (v2) Solve a rule on AERO solver and get the result in the same call. {% hint style="info" %} Available for server versions ≥ 1.27.0 {% endhint %} The Rule Solver API is the main way to evaluate your rules from your own application. You send the input data, and the rule — a Decision Table, Decision Tree, Decision Flow or any other rule type — returns its output in the same call. This page describes version 2 of the API. It runs on **solver v2**, also called **AERO**, where all new features are released. {% hint style="info" %} **Already calling the Rule Solver API?** \ If you use `/rule/solve/` or `/rule/v1/solve/`, see [Rule Solver API Migration](/doc/api/rule-solver-api/solver-version-migration.md). {% endhint %} {% hint style="success" %} In version 1.16.0 and newer Rule Flows are solved with this endpoint too. The separate Rule Flow Solver API is deprecated. **Note that Rule Flows are always evaluated by GAIA (v1) solver.** See [Exceptions](#exceptions). {% endhint %} ## Introducing AERO {% embed url="" %} Below you will find the specification of this endpoint. ## Swagger You can check out these endpoints and call them right away using swagger. **Swagger UI:** [https://api.decisionrules.io/api/solver/docs](https://api.decisionrules.io/api/solver/docs/) **Swagger JSON File:** ## Solve Rule (v2 Aero) > Solves the rule on solver v2 (Aero), where all new features are released. If the \`{ruleVersion}\` parameter is omitted from the path, the last published rule version will be used automatically. ```json {"openapi":"3.0.3","info":{"title":"DecisionRules Rule Solver API","version":"1.2.0"},"tags":[{"name":"Rule Solver API v2"}],"servers":[{"url":"https://api.decisionrules.io"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Please insert: \"Bearer \" into Authorization header."}},"parameters":{"ruleId":{"name":"ruleId","in":"path","required":true,"description":"Unique identifier for the rule that is common to all rule versions. Instead of rule ID, it is possible to use a rule alias.","schema":{"type":"string"}},"ruleVersion":{"name":"ruleVersion","in":"path","required":false,"description":"Rule version. If not provided, the latest published version is used.","schema":{"type":"integer"}},"ContentType":{"name":"Content-Type","in":"header","required":false,"description":"The media type of the request body.","schema":{"type":"string"}},"XStrategy":{"name":"X-Strategy","in":"header","required":false,"description":"Execution strategy used to evaluate the rule. See [Execution Strategy](https://docs.decisionrules.io/doc/rules/common-rule-features/execution-strategy).","schema":{"type":"string","enum":["STANDARD","FIRST_MATCH","ARRAY","EVALUATE_ALL"]}},"XLookupMethod":{"name":"X-Lookup-Method","in":"header","required":false,"description":"Lookup method, used only with Lookup Tables.","schema":{"type":"string","enum":["LOOKUP_EXISTS","LOOKUP_VALUE"]}},"XCorrelationId":{"name":"X-Correlation-Id","in":"header","required":false,"description":"Correlation ID, if you'd like to set it manually. If not present, it will be generated automatically and returned in the response.","schema":{"type":"string"}},"XDebug":{"name":"X-Debug","in":"header","required":false,"description":"On-premise deployments only: set to `true` to solve rules with the status pending. On DecisionRules Cloud this header has no effect.","schema":{"type":"string","enum":["true","false"]}},"XAudit":{"name":"X-Audit","in":"header","required":false,"description":"Whether to create and save an audit of the solve.","schema":{"type":"string","enum":["true","false"]}},"XAuditTtl":{"name":"X-Audit-Ttl","in":"header","required":false,"description":"Number of days after which the audit will be deleted. Default is 14 days.","schema":{"type":"string"}}},"requestBodies":{"SolveBody":{"required":true,"description":"Request body containing the input data and solver options.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"JSON object that describes the input json data."},"options":{"type":"object","description":"Object specifying solver options."}}}}}}},"responses":{"Solved":{"description":"OK","headers":{"X-Solver-Version":{"$ref":"#/components/headers/XSolverVersion"},"X-Solver-Engine":{"$ref":"#/components/headers/XSolverEngine"},"X-Correlation-Id":{"$ref":"#/components/headers/XCorrelationIdHeader"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"BadRequest":{"description":"Bad Request. Returned for an unknown rule, a missing API key, or a request body that does not match the expected shape.","headers":{"X-Solver-Version":{"$ref":"#/components/headers/XSolverVersion"},"X-Solver-Engine":{"$ref":"#/components/headers/XSolverEngine"}},"content":{"application/json":{"schema":{"type":"object"}}}},"Unauthorized":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object"}}}}},"headers":{"XSolverVersion":{"description":"Solver version that evaluated the request, errors included.","schema":{"type":"string"}},"XSolverEngine":{"description":"Name of the solver engine that evaluated the request.","schema":{"type":"string"}},"XCorrelationIdHeader":{"description":"Correlation ID of the request.","schema":{"type":"string"}}}},"paths":{"/rule/v2/solve/{ruleId}/{ruleVersion}":{"post":{"tags":["Rule Solver API v2"],"summary":"Solve Rule (v2 Aero)","description":"Solves the rule on solver v2 (Aero), where all new features are released. If the `{ruleVersion}` parameter is omitted from the path, the last published rule version will be used automatically.","parameters":[{"$ref":"#/components/parameters/ruleId"},{"$ref":"#/components/parameters/ruleVersion"},{"$ref":"#/components/parameters/ContentType"},{"$ref":"#/components/parameters/XStrategy"},{"$ref":"#/components/parameters/XLookupMethod"},{"$ref":"#/components/parameters/XCorrelationId"},{"$ref":"#/components/parameters/XDebug"},{"$ref":"#/components/parameters/XAudit"},{"$ref":"#/components/parameters/XAuditTtl"}],"requestBody":{"$ref":"#/components/requestBodies/SolveBody"},"responses":{"200":{"$ref":"#/components/responses/Solved"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"operationId":"solveRuleV2"}}}} ``` ## Request example ```html URL https://api.decisionrules.io/rule/v2/solve/{ruleId}/{ruleVersion} Headers: Content-Type: application/json Authorization: Bearer ``` `{ruleVersion}` is optional. Leave it out, as in `/rule/v2/solve/{ruleId}`, and the latest published version of the rule is used. For easy Rule Solver API calls go to **Integrations → Code Samples**. Note that the cURL code can be copy/pasted directly to Postman.
If you're using the Regional Cloud version of DecisionRules, read more about API calls [here](/doc/v1/regional-cloud/region-specific-api-urls.md). Note that you can use the rule alias instead of the rule ID to identify the rule. In that case, make sure that the rule alias is unique within the space, otherwise the request will fail. You must provide your own API key after the `Bearer` keyword. Generate it in the [API Keys](/doc/api/api-keys.md) section of the app. ### **Body** The body of the request needs to have the following structure. ```json { "data": { // INPUT OBJECT } } ``` For example, it may look as follows. The object under the `data` key needs to correspond to the input model of the rule you want to solve, see [I/O Model](/doc/rules/common-rule-features/input-and-output.md). ```json { "data": { "client": { "age": 18 } } } ``` If the input is not wrapped in `data`, the request is rejected with `400`. See [Invalid requests](#invalid-requests). {% hint style="warning" %} **`data`** is part of the API request, not part of your rule. It is the envelope the Solver API expects, and it exists only here: * **In the I/O Model**, define the fields of the input object itself — `client`, `age`, and so on. Do not add a `data` field to the model. * **In Test Bench**, enter the input object itself, without the wrapper. Test Bench sends it for you. {% endhint %} ### Options The request body can contain an optional `options` object that configures how the rule is solved. Each option below says which rule types it applies to. #### **Included Condition Cols** **Decision Tables only.** Specifies the condition columns to evaluate; all other columns are ignored. Columns are identified by the name of the input variable related to the column. ```javascript { "data": { "client": { "age": 18 }, "productCount": { "accountsAndCards": 4, "Investments": 4 }, "portfolioAmount": 15000 }, "options": { "includedConditionCols": ["client.age", "portfolioAmount"] } } ``` With this configuration, only the columns related to `client.age` and `portfolioAmount` are evaluated. The columns for `productCount.accountsAndCards` and `productCount.Investments` are ignored, even though their values are sent. #### **Excluded Condition Cols** **Decision Tables only.** Specifies the condition columns to ignore. Columns are identified by the name of the input variable related to the column. ```javascript { "data": { "client": { "age": 18 }, "productCount": { "accountsAndCards": 4, "Investments": 4 }, "portfolioAmount": 15000 }, "options": { "excludedConditionCols": ["client.age", "portfolioAmount"] } } ``` With this setup, the columns related to `client.age` and `portfolioAmount` are ignored, and only the `productCount` columns are evaluated. {% hint style="warning" %} `includedConditionCols` takes precedence over `excludedConditionCols`. If you specify both, the excluded columns are ignored. We recommend using only one of them. {% endhint %} #### **Quit Solve On Fail** Determines whether a failed HTTP function call stops the solve. Applies to HTTP functions used directly in the rule you call — in a Decision Table, Decision Tree or Decision Flow. ```javascript { "data": { // INPUT OBJECT }, "options": { "quitSolveOnFail": true } } ``` When set to `true`, an error from an HTTP function — HTTP\_GET, HTTP\_POST, HTTP\_PUT, HTTP\_PATCH or HTTP\_DELETE — stops the solve, and the Rule Solver API returns an error response instead of 200. In Flows, errors from parallel branches and bulk executions stop the solve too. When the option is omitted or set to `false`, a failed HTTP call does not stop the solve. ### Invalid requests The solver checks the request before running the rule, and returns `400` with a message that says what is wrong: | Request | Message | | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Empty body or malformed JSON | `request body must be valid JSON` | | Input not wrapped in `data`, e.g. `{"creditScore": 700}` | `unexpected top-level field 'creditScore'; input data must be wrapped in "data"` | | `data` is not an object, e.g. `{"data": "hello"}` | `solve data must be an object or array of objects` | | A bulk array with a non-object in it | `bulk solve data item 1 must be an object` | | `options` is not an object | `options must be an object` | A rule that takes no input can be called with `{}`. ## Simple Solve Simple solve means that you send a single set of input data and the solver thus evaluates this single input. The response is an array of results (given e.g. by the individual rows of a decision table).
### Simple Request This is how the object sent under the `data` key could look for the given rule. ```json { "client": { "age": 18 }, "productCount": { "accountsAndCards": 4, "Investments": 4 }, "portfolioAmount": 15000 } ``` ### Simple Response And this would be the response. Only one row of the decision table was triggered, so the output is an array with a single object, holding the outputs set on that row. ```json [ { "totalProducts": 8, "amountPerProduct": 1875, "client": { "segment": "senior affluent" }, "profitability": 1 } ] ``` ## Bulk Solve On the other hand, DecisionRules also supports the bulk solve, which is a call to the solver where you include multiple sets of input data. Each set is evaluated individually, with no relation to any other, and the solver returns an array of the corresponding output objects.
### Bulk Request This is how the JSON under the `data` key of a bulk request is structured. Instead of an input data object, you send an array of these objects. ```json [ { // first input "product": { "id": "P1", "price": 400 }, "paymentMethod": { "debitCard": true, "creditCard": false, "cash": {} } }, { // second input "product": { "id": "P2", "price": 300 }, "paymentMethod": { "debitCard": true, "creditCard": {}, "cash": {} } } ] ``` ### Bulk Response The outer array corresponds to the array sent in the request. Each inner array holds the results for one input, just as in a simple solve. In this example, one row of the decision table was triggered for each input. ```json [ [ // results for the first input { "suplier": "Amazon", "amount": 400 } ], [ // results for the second input { "suplier": "Lenovo", "amount": 300 } ] ] ``` ## How the solver version is applied Requests to this endpoint are evaluated by solver AERO (v2). This section explains how to check which version evaluated a request, how the version carries over to the rules a rule calls, and the few cases where solver GAIA (v1) is used instead. ### Response headers Every response says which solver version evaluated the request, errors included: ``` X-Solver-Version: v2 X-Solver-Engine: aero ``` A response from solver GAIA (v1) carries `v1` and `gaia`. {% hint style="info" %} The response also contains `X-Version`, and that is the version of **your rule**, not the solver. {% endhint %} ### Rules that call other rules When a rule calls another rule — from a flow node, a function or a script — the called rule runs on the same solver version. You choose the version once, in the call you make. ### Exceptions [**Rule Flows**](/doc/rules/rule-flow.md) and [**AI Agents**](/doc/rules/ai-agent.md) are always evaluated by GAIA (v1), whichever version you call. You can still call these rules with any version. When you call one directly, the response header and the audit show `v1`, because that is the version that evaluated it. {% hint style="info" %} Inside a Decision Flow, only that node runs on GAIA(v1). The rest of the flow runs on the version you called, and the response header shows that version. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decisionrules.io/doc/api/rule-solver-api/rule-solver-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.