> 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/solver-version-migration.md).

# Rule Solver API Migration

This page is for you if you already have something calling DecisionRules and you are thinking about moving it to new Solver.

### What to expect

Your rules give the same answers on both engines. This is not a rewrite of how rules are evaluated — it is a new engine running the same logic, and we test both against the same cases to keep it that way.

So the expected outcome of this migration is that nothing changes except which engine handled the request. That said, **we do not recommend switching production over in one go.**

Before you start, read [Invalid requests](/doc/api/rule-solver-api/rule-solver-api.md#invalid-requests) in AERO solver.

### Docker and On-Premise capacity

Before switching to AERO (v2), apply the [AERO server profile](/doc/decisionrules-applications/server-app.md#minimal-requirements). AERO can use more CPUs per replica while `WORKERS_NUMBER` remains set to `1`.

### Migration steps

#### **1. Make sure both versions are available**

Open **Space Settings** **→** [**Solver Versions**](/doc/space/settings.md#solver-versions) in the space you are migrating and check that both the versions you use today and the one you are moving to are selected.

With both selected, you can pick the solver for each run.

If you work under organization, the list of spaces in **Organization → Resources →** [**Spaces**](/doc/organization/resources/spaces.md) shows which versions each space has.

#### 2. Run your tests on AERO (v2)

If you have tests for your rules, run them against the new engine before changing anything in your integration. Nothing else in your setup needs to change. You pick the version for each run: in the [Tests Tab](/doc/space/tests/tests-tab.md) or in [Test Bench](/doc/rules/common-rule-features/test-bench.md), and in the [Rule Testing API](/doc/api/rule-testing-api.md) with `solverVersion` if you run tests from CI.

See [Rule testing](https://docs.decisionrules.io/doc/rules/common-rule-features/rule-testing) for how to set tests up and run them.

{% hint style="info" %}
**No tests yet?** This is a good moment to write a few, and our [AI assistant can generate them](/doc/ai-assistant/ai-assistant-features.md#generate-test-data) for you from your existing rules.
{% endhint %}

#### 3. If something does not match

Both versions should give the same result for the same rule and input. If they don't, that's something for us to look into, and you shouldn't have to work around it. Before you contact us, a few quick checks will tell you whether the difference really comes from the solver, and they often find the cause straight away.

**Check the rule**

* **Reproduce it in Test Bench.** Run the same input on both versions in [Test Bench](/doc/rules/common-rule-features/test-bench.md#solver-version). If the results match there but not in your integration, the difference is in how your code calls us.

**Check the request**

* **Is it one of the documented differences?** A `400` on AERO (v2) that you never saw on GAIA (v1) usually means the request body is one of the cases in [Invalid requests](/doc/api/rule-solver-api/rule-solver-api.md#invalid-requests).
* **Same input, same strategy.** Compare the exact body and the `X-Strategy` header of both calls. A different strategy gives a different result on either version.

**Check that the call went where you think it did**

* **The response header.** Look at `X-Solver-Version` in both responses. If both say the same version, the difference is not between solvers. If a call you sent to `/v2/` says `v1`, see [Exceptions](/doc/api/rule-solver-api/rule-solver-api.md#exceptions).
* **The rule version.** A call without a version uses the latest published one. If you compare a test against a call without a version, you may be comparing two different versions of the rule.
* **The space.** The API key decides which space the rule comes from. Make sure both calls use a key for the same space.

**If the difference is still there,** [**contact support**](https://support.decisionrules.io/support/home) **and send:**

* the rule which fails
* the input you sent
* what you expected and what you got instead

{% hint style="warning" %}
**Please, do not change your rule to make the V2 output match V1.**
{% endhint %}

#### 4. Switch over

Once your tests pass on AERO (v2), switch each place that calls DecisionRules:

* **Rule Solver API** — change the path:

```
POST /rule/solve/{ruleId}/{ruleVersion}        # before
POST /rule/v1/solve/{ruleId}/{ruleVersion}     # before, if you already name V1
POST /rule/v2/solve/{ruleId}/{ruleVersion}     # after
```

* **Jobs API** — add `"solverVersion": "v2"` to the request body. See [Jobs API](/doc/api/jobs-api.md).
* **Rule Testing API** — if you run tests from CI, set `"solverVersion": "v2"` there too, so your tests keep running on the version production uses.

Move one integration at a time and watch it before doing the next. Every response carries `X-Solver-Version`, so log it during the switch.

**If something goes wrong, change the path back.** Nothing is stored, nothing is converted, and your rules are untouched — the engine is chosen per request. Switching to new version is not a commitment, and you can run one endpoint on new version while everything else stays on old one for as long as you like.

### What tests will not catch

Running your rules inside DecisionRules proves the two engines agree on your logic, and that is the important part. What it cannot check is how *your own code* builds the request — a test suite sends a well-formed body every time.

So if you start seeing `400`s on AERO (v2) that you never saw on GAIA (v1), the engine is not the problem. AERO (v2) is telling you about something your code was already doing, and GAIA (v1) was accepting quietly.

The requests AERO (v2) rejects are listed in [Invalid requests](/doc/api/rule-solver-api/rule-solver-api.md#invalid-requests).


---

# 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/solver-version-migration.md?ask=<question>&goal=<user_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.