Optimisation Service Documentation

Three ways to access the service, depending on how much you want it to do for you. All three ultimately talk to the same REST API — you choose the level of abstraction that fits your situation.

Any language

REST API

Submit models in MPS or LP format over HTTP. The foundation that everything else is built on.

Java

Client Library

A lightweight Java client with a fluent modelling API and a simple HTTP facade. One Maven dependency, zero transitive dependencies.

ojAlgo users

ojAlgo Integration

Plug the service into ExpressionsBasedModel. Your existing models solve remotely without code changes.

Running the service

The Optimisation Service is a container image that you run on your own infrastructure. To get started and to run tests without installing anything, there is also a public shared instance at https://service-api.optimatika.se. It is not for production: in production, always run your own instance. Without a licence key it is free, needs no sign-up, and has the limits of restricted mode. With a key, sent with each request as Authorization: Bearer <key>, it runs the full solver suite on models of up to 10,000 variables or constraints, stops a solve after 60 minutes, or after 30 once it has a feasible solution, and bills its usage, in core-minutes, to the key’s subscription. It runs as several instances, so follow a solve over a stream rather than by polling. Abort a solve you no longer want: a solve whose client goes away without its abort getting through — the program crashes or loses its connection, or, rarely, the abort reaches another instance — runs on until it finishes or reaches its time limit, and its usage is billed. Do not send it anything confidential. On your own deployment, Optimatika never sees your models.

Obtaining the image

The image is public. There is no registry account to create, no credentials to configure and no pull secret to manage in your cluster:

docker pull ghcr.io/optimatika/optimisation-service

Run without a licence key and the server starts in restricted mode — ojAlgo’s own solvers, on a single core, for models of up to 1,000 variables or constraints, and a solve stops after 60 seconds, or after 30 once it has a feasible solution. That is a working server, free forever. A larger model is refused: its result comes back FAILED, and the server log says why. A licence key, obtained with an Optimatika Subscription, unlocks the full solver suite, every vCPU you give the server, and the limits below.

Licensed, a server accepts models of up to 100,000 variables or constraints, and stops a solve after 24 hours, or after one hour once it has a feasible solution. OPTIMATIKA_MAX_SIZE, OPTIMATIKA_TIME_ABORT and OPTIMATIKA_TIME_SUFFICE (in seconds) change those limits, and 0 removes one. They apply in restricted mode too, which never goes beyond its own.

Licence key and usage

A subscription issues one licence key. Set it on the deployment:

OPTIMATIKA_LICENCE_KEY=your-key

Or, to read it from a file, such as a mounted secret:

OPTIMATIKA_LICENCE_KEY_FILE=/etc/optimatika/licence-key

The subscription is billed by use, in core-minutes: each solve counts the time from when it starts to when it ends, × the threads it is given, while the server runs licensed. Waiting in the queue is free, and so is a server with nothing to solve. Every instance counts its own. The subscription includes an amount each period, and use beyond it is billed at the end of the period.

How many solves run at a time, and with how many threads each, is yours to set:

OPTIMATIKA_WORKERS=2
OPTIMATIKA_THREADS=4

By default two solves run at a time, each with half the CPUs the container has. Set one and the other fills the CPUs. More threads than CPUs is allowed, with a warning in the log: a solve is billed the threads it is given, whether it keeps them busy or not.

Every five minutes the server reports its usage to Optimatika: the licence key, an instance id chosen at random when it starts, the period, the solves it runs at a time and their threads, and the core-minutes used. Models, data and results are never sent. The answer says whether the key is in force, and that is the server’s licence check. The server needs outbound HTTPS to Optimatika for it: to www.optimatika.se, where it looks up where to report, and to the address it finds there.

The solves and threads are decided once, when the server starts: as set if the key was in force or Optimatika could not be asked, one solve on one thread if the key was not in force. A restart picks up a change.

GET /optimisation/v1/environment reports where the licence stands. That is the check to run after deploying a key.

The container

The image listens on port 8080 (set PORT to change it) and speaks plain HTTP. GET /health answers with a status code and no body, for whatever health checks your platform runs.

One instance per address. A submitted model, its status and its result are held in memory by the instance that accepted it, so every request about it — a poll, a reconnect, an abort — has to reach that same instance. One instance per address is the supported set-up. To add capacity, give the instance more cores, or run separate instances and point different clients at each.

CPU between requests. The server works when no request is open too: it solves while a client is between polls, and it reports its usage every five minutes. On a platform that throttles the CPU between requests, turn that off — on Cloud Run, --no-cpu-throttling.

CPU and memory. Solvers are CPU-bound and several are multi-threaded, so give the container whole cores rather than fractions if you are solving anything substantial — 2–4 vCPU is a reasonable starting point for production models. Memory scales with model size rather than with request volume.

GET /optimisation/v1/environment reports what the running server actually sees — its build, CPUs and memory, licence and solvers — which is the quickest way to confirm it got what you intended.

Security

The API is unauthenticated. There is no API key, no token and no built-in authorisation of any kind. This is deliberate: the service is designed to run inside your own network, where your existing controls apply, rather than to re-implement an identity system you already have.

The consequence is that reachability is your access control, so the deployment must not be publicly reachable:

There is no per-caller rate limiting. Apart from the limits on size and solve time above, the only backpressure is the work queue, which holds 128 pending problems and returns 429 once full — that protects the server from overload, but it does not stop one caller from filling the queue. Treat access as you would access to a compute cluster.

Submitted models and results are held in memory only, in caches that expire one hour after last access. Nothing is written to disk, and nothing is transmitted off the instance.

Status codes

CodeMeaning
200Success. For poll-result, check the returned status — 200 means the request succeeded, not that the solve has finished.
400Malformed request — an unparseable model, or an unknown format or sense in the path.
404Unknown endpoint, or a result key that has expired or never existed.
405Wrong HTTP method for that path.
429The work queue is full. Retry with backoff.
500The solve or translation failed unexpectedly.

Error responses carry the status code and an empty body; the detail is written to the container log. The server stops a solve at its time limits, which by default allow a large mixed-integer model to run for many hours by design; set a client-side timeout to match what you are prepared to wait.

REST API

The service exposes a small HTTP API. You submit a serialised model, receive a queue key, and poll until the result is ready. The protocol is intentionally simple — any language with an HTTP client can use it.

Base URL

The base URL is the address of your deployed service instance, e.g. https://your-service-host. All endpoints are relative to this.

Endpoints

Method Path Description
POST /optimisation/v1/put-on-queue/{format}/{sense} Submit a model for solving
GET /optimisation/v1/poll-result/{key} Check status and retrieve the solution
POST /optimisation/v1/translate/{from}/{to} Convert a model between formats
POST /optimisation/v1/abort/{key} Abandon a queued or running solve
GET /optimisation/v1/environment Which build is running, what its licence permits, which solvers it has, and how many solves it runs at once and is running now
GET /health Health check for probes; a status code and no body

The complete specification is published as an OpenAPI document: openapi.yaml. Load it into any OpenAPI tool to browse the API or generate a client.

curl -s https://your-service-host/optimisation/v1/environment
{"build":{"module":"polar","built":"2026-10-01T11:46:07Z","commit":"66f8636","branch":"develop","dirty":"false"},
 "runtime":"1GB/4threads x86_64 [...]",
 "licence":"Polar (licensed — full solver suite, usage billed in core-minutes)",
 "solvers":{"probed":true,"available":["LP-HiGHS","LP-JVM","MILP-SCIP", ...]},
 "capacity":{"workers":2,"threadsPerWorker":2,"running":1,"queued":0}}

Just after a start the server is still probing its solvers: probed is false and only the pure-Java solvers are listed. Ask again a few seconds later for the full list.

Submit a model

POST /optimisation/v1/put-on-queue/{format}/{sense}

Path parameters:

ParameterValuesDescription
format MPS, LP The format of the request body. MPS is the industry standard; LP is the CPLEX LP format. Both are plain text and are written by virtually every optimisation tool.
sense MIN, MAX Whether to minimise or maximise the objective.

The request body is the raw model bytes. The response is JSON:

{
  "key": "PmkvX3SNQ0gjRtCD",
  "status": "PENDING"
}

The key is the queue identifier you use to poll for the result.

Poll for the result

GET /optimisation/v1/poll-result/{key}

While the solver is working, the response has "status": "PENDING". When done:

{
  "key": "PmkvX3SNQ0gjRtCD",
  "status": "DONE",
  "result": "OPTIMAL 13.0 @ { 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 }"
}

The result string has three parts: the solver state (OPTIMAL, FEASIBLE, INFEASIBLE, etc.), the objective value, and the solution vector.

A key the server does not know — it has expired, or the request reached another instance — gets 404.

Follow a solve over a stream

Send Accept: text/event-stream with put-on-queue or poll-result, and the request stays open instead of answering once. It sends server-sent events, each the JSON object that poll-result returns: the status at once, with the key, then again every 15 seconds while the solve is pending, and finally the one with the result, after which the stream ends. If the connection is cut, the solve goes on, and a streamed poll-result with the key follows it again. The Java client does this by itself, from version 1.1.0.

On Optimatika’s shared instance, follow every solve this way: it runs as several instances, and the stream keeps you on the one solving your model, where a later poll may reach another.

A grace period for solves nobody follows any longer can be set on your own deployment: OPTIMATIKA_DETACH_GRACE, in seconds. A solve with no stream open and no poll for that long is aborted, as by abort. By default there is none. A longer grace rides out longer network drops; a shorter one frees the worker, and bills less, sooner after a client has gone. The server notices a closed stream when its next status event fails to write, within about 30 seconds. Behind a proxy that keeps its side of the connection open after the client has gone — Cloud Run does — it never notices: a streamed solve then runs on until it finishes or is aborted, and only polled solves are ended by the grace period.

Translate between formats

POST /optimisation/v1/translate/{from}/{to}

Converts a model between EBM, MPS, and LP formats. The request body is the model in the input format; the response body is the model in the output format.

Example with curl

# Check that the service is running (prints the HTTP status, 200 when healthy)
curl -s -o /dev/null -w "%{http_code}\n" https://your-service-host/health

# Submit an MPS model for minimisation
KEY=$(curl -s -X POST \
  -H "Content-Type: application/octet-stream" \
  --data-binary @model.mps \
  https://your-service-host/optimisation/v1/put-on-queue/MPS/MIN \
  | jq -r '.key')

# Poll for the result
curl -s https://your-service-host/optimisation/v1/poll-result/$KEY

Client Library

The client library is a single Maven dependency with zero transitive dependencies. It provides two things: a thin HTTP client (OptClientV1) and a lightweight modelling API (OptModel). Use either or both.

Add the dependency

<dependency>
    <groupId>se.optimatika</groupId>
    <artifactId>optimisation-service-client</artifactId>
    <version>1.1.0</version>
</dependency>

Quick start

Build a model, solve it, read the result — all in a few lines:

// Connect to the service
OptClientV1 client = OptClientV1.newInstance("https://your-service-host");

// Build a model
OptModel model = client.newModel();

OptVariable x = model.newRealVariable("x").lower(0);
OptVariable y = model.newRealVariable("y").lower(0);

model.newConstraint("budget").set(x, 1).set(y, 1).upper(10);

model.getObjective().set(x, 3).set(y, 5);

// Solve remotely (returns a Future)
OptResult result = model.maximise().get();

System.out.println("Optimal: " + result.isOptimal());
System.out.println("Value:   " + result.doubleValue());
System.out.println("x = " + x.doubleValue());
System.out.println("y = " + y.doubleValue());

With a licence key

On the shared instance, give the client your licence key, and it sends it with every request as Authorization: Bearer — from version 1.1.0:

OptClientV1 client = OptClientV1.newInstance("https://service-api.optimatika.se",
        System.getenv("OPTIMATIKA_LICENCE_KEY"));

Everything else stays the same, OptModel included. A deployment of your own takes its key from its environment and ignores the header. Send a key only over HTTPS.

The two layers

The client is split into two independent layers that you can use separately:

OptClientV1 is a thin HTTP facade. It knows how to submit bytes to the server and parse the JSON response, but knows nothing about what a model looks like. You can use it standalone to submit MPS or LP files, or any other format the server supports.

OptModel is a model builder. It provides the fluent API for variables, constraints, and objectives, handles serialisation, and manages the polling loop and result mapping. It delegates all HTTP communication to an OptClientV1 instance.

This separation means you can use the HTTP client directly without the model builder, submit MPS files from other tools, or replace the model builder entirely.

HTTP client directly

If you already have models in MPS format or want full control over the submit/poll cycle:

OptClientV1 client = OptClientV1.newInstance("https://your-service-host");

// Submit an MPS file
byte[] mpsData = Files.readAllBytes(Path.of("model.mps"));
String response = client.putOnQueue(mpsData, "MPS", false); // false = minimise

// Or use the parsed variant
Map<String, Object> parsed = client.putOnQueueParsed(mpsData, "MPS", false);
String key = (String) parsed.get(OptClientV1.KEY);

// Poll until done
Map<String, Object> poll = client.pollResultParsed(key);
while ("PENDING".equals(poll.get(OptClientV1.STATUS))) {
    Thread.sleep(100);
    poll = client.pollResultParsed(key);
}

OptResult result = (OptResult) poll.get(OptClientV1.RESULT);

Model builder API

The OptModel builder supports real, integer, and binary variables, linear constraints, and linear and quadratic objectives. It is written much like ojAlgo’s ExpressionsBasedModel — see ExpressionsBasedModel and OptModel, side by side.

OptModel model = client.newModel();

// Variable types
OptVariable x = model.newRealVariable("x").lower(0).upper(100);
OptVariable n = model.newIntegerVariable("n").lower(0).upper(10);
OptVariable b = model.newBinaryVariable("use_option");

// Constraints with bounds
model.newConstraint("capacity")
     .set(x, 2.5).set(n, 1)
     .upper(50);

model.newConstraint("minimum")
     .set(x, 1).set(b, -10)
     .lower(0);

// Objective
model.getObjective().set(x, 3).set(n, 7);

// Solve
OptResult result = model.minimise().get();

Classes

ClassRole
OptClientV1HTTP client — submits models and polls for results
OptModelModel builder — variables, constraints, objective, serialisation
OptVariableDecision variable (real, integer, or binary)
OptConstraintLinear constraint with bounds
OptObjectiveObjective function (linear or quadratic)
OptExpressionBase for constraints and objectives — holds coefficients
OptResultImmutable result — solver state, objective value, solution vector

ojAlgo Integration

If you already use ojAlgo, this is the most natural way to access the service. Wire the client into ExpressionsBasedModel, and the code that builds your models stays as it is. To move a model to the client’s own OptModel instead, or back, see ExpressionsBasedModel and OptModel, side by side.

Setup

You need both ojAlgo and the service client on the classpath. The integration uses ojAlgo's Optimisation.Environment to register the service as a remote solver:

OptClientV1 client = OptClientV1.newInstance("https://your-service-host");

Optimisation.Environment environment = Optimisation.newEnvironment();
environment.setRemoteSolver(client::putOnQueue, client::pollResult);

This works because the putOnQueue and pollResult method signatures match ojAlgo's Optimisation.ModelSubmitter and Optimisation.ResultPoller functional interfaces.

Solve remotely

Once the environment is configured, create models from it and submit them:

ExpressionsBasedModel model = environment.newModel();

Variable x = model.newRealVariable("x").lower(0);
Variable y = model.newRealVariable("y").lower(0);

model.newConstraint("budget").set(x, 1).set(y, 1).upper(10);

model.getObjective().set(x, 3).set(y, 5);

// Solve via the service (returns a Future)
Optimisation.Result result = model.submit(Optimisation.Sense.MAX).get();

System.out.println("Optimal: " + result.isOptimal());
System.out.println("Value:   " + result.doubleValue());
System.out.println("x = " + x.doubleValue());
System.out.println("y = " + y.doubleValue());

The model is serialised, sent to the service, solved by the best available solver on the server, and the result is returned — all through the standard ojAlgo API. The code that builds the model is the same as for solving locally. What differs is where the model comes from, environment.newModel(), and the call that solves it: submit(…), not minimise() or maximise(), which always solve in your JVM. Written this way, with ojAlgo 57.7.0 or later, it reads the same as the client library’s Quick start with OptModel.

Develop locally, solve remotely

The intended workflow: during development, solve locally with ojAlgo's built-in pure-Java solvers. No server needed, no network dependency, fast iteration. When you deploy to production, configure the environment to point at the service and let it solve the same models at production scale, without installing anything.

// Development: solve locally (no environment setup needed)
ExpressionsBasedModel model = new ExpressionsBasedModel();
// ... build model ...
Optimisation.Result localResult = model.minimise();

// Production: same model, solve via the service
Optimisation.Environment env = Optimisation.newEnvironment();
env.setRemoteSolver(client::putOnQueue, client::pollResult);

ExpressionsBasedModel model = env.newModel();
// ... same model building code ...
Optimisation.Result remoteResult = model.submit(Optimisation.Sense.MIN).get();

Supported problem types

The service handles the main classes of mathematical optimisation problems: linear programming (LP), quadratic programming (QP), and mixed-integer programming (MIP), including mixed-integer linear (MILP) and mixed-integer quadratic (MIQP). The server selects the best available solver for each problem type automatically.

Model formats

FormatDescription
MPS Industry-standard Mathematical Programming System format. Supported by virtually all optimisation tools. Use this when submitting models from non-Java environments.
LP CPLEX LP format. Also plain text, and often easier to read and hand-edit than MPS. Use either this or MPS when submitting models from non-Java environments.
EBM ojAlgo's native ExpressionsBasedModel serialisation format. This is what the client library and the ojAlgo integration use on the wire — you do not choose it yourself, and you do not need to know about it unless you are calling the REST API directly with an ojAlgo model in hand.

Bugs and questions

Found a bug in the server or the client? Report it in optimisation-service-client issues — anyone can. With a subscription, start a support case through the contact form instead; that is where the response time applies. See ojAlgo Support.

Back to Optimisation Service