The NexOR Optimization API

Your first solve, in three steps

From zero to a real answer in minutes. A two-product production mix: maximise margin under machine-hour and material limits. The optimum is 30 chairs and 5 tables, objective 1750.

1. Copy an API key

   Give it any name and pick an expiration, that is the whole form. This key is what identifies you on every API call you make. The secret is shown once, so copy it right away. This is the only step that happens in the browser.

   Open API keys

2. Submit, wait, fetch

   Paste your key into the example below and run it: submit the envelope, hold one request open until the problem ends, then fetch the solution. This is the shortest path from a laptop, where nothing can receive a webhook. Once you run a server, register a webhook and drop the middle step.

# Set these once. BASE is your NexOR host; the key comes from your portal.
export BASE="https://<your-nexor-host>/solve/v1"
export API_KEY="<your-api-key>"

# 1. Submit the envelope (saved as envelope.json).
curl -s -X POST "$BASE/problems" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @envelope.json
# -> {"problem_id":"prb_9f3c...","status":"queued","time_limit_seconds":5,...}

# 2. Wait. The request stays open until the problem ends, and timeout_seconds
#    is capped at 60, so repeat the call while the status is queued or running.
#    A server registers a webhook instead and skips this step altogether.
curl -s -X POST "$BASE/problems/prb_9f3c.../wait?timeout_seconds=60" \
  -H "Authorization: Bearer $API_KEY"
# -> the snapshot, with "outcome" set once the solve has ended

# 3. Fetch the solution. Without inline=1 the route answers 302 to a presigned
#    object URL, so a plain curl prints nothing; pass -L to follow it instead.
curl -s "$BASE/problems/prb_9f3c.../result?inline=1" \
  -H "Authorization: Bearer $API_KEY"
# -> {"problem_id":"prb_9f3c...","outcome":"solved","solution":{
#     "outcome":"solved","termination_status":"OPTIMAL","objective_value":1750.0,
#     "result":{"values":{"chairs":30.0,"tables":5.0}}}}

import os, time, requests

BASE = os.environ["SOLVE_BASE"]      # https://<your-nexor-host>/solve/v1
HEAD = {"Authorization": f"Bearer {os.environ['SOLVE_API_KEY']}"}

envelope = {
    "api_version": "1",
    "problem": {
        "variables": [{"name": "chairs", "lower": 0}, {"name": "tables", "lower": 0}],
        "constraints": [
            {"expr": "4*chairs + 8*tables <= 160", "name": "machine_hours"},
            {"expr": "2*chairs + 3*tables <= 75", "name": "material"},
        ],
        "objective": {"sense": "max", "expr": "45*chairs + 80*tables"},
    },
    "solver": "highs",
    "options": {"compute_preset": "cpu-standard", "time_limit_seconds": 5},
}

# 1. Submit.
prb = requests.post(f"{BASE}/problems", json=envelope, headers=HEAD).json()
print("submitted", prb["problem_id"], prb["status"])

# 2. Wait. The request is held open until the problem ends; the 60 second cap
#    means a longer solve answers a snapshot that is not terminal yet, so the
#    call is repeated. For live progress open GET /problems/{id}/events instead.
RUNNING = {"queued", "running"}
while True:
    reply = requests.post(
        f"{BASE}/problems/{prb['problem_id']}/wait",
        params={"timeout_seconds": 60},
        headers=HEAD,
    )
    if reply.status_code == 429:                 # asked to slow down
        time.sleep(int(reply.headers.get("Retry-After", 5)))
        continue
    reply.raise_for_status()
    state = reply.json()
    if state["status"] not in RUNNING:
        break

# 3. Fetch the solution.
reply = requests.get(f"{BASE}/problems/{prb['problem_id']}/result", headers=HEAD)
while reply.status_code == 429:              # a burst of submits spent the budget
    time.sleep(int(reply.headers.get("Retry-After", 5)))
    reply = requests.get(f"{BASE}/problems/{prb['problem_id']}/result", headers=HEAD)
reply.raise_for_status()                     # 410 once past retention
sol = reply.json()
print("outcome:", sol["outcome"])                              # "solved"
print("objective:", sol["solution"]["objective_value"])        # 1750.0
print("values:", sol["solution"]["result"]["values"])  # {"chairs": 30.0, ...}

{
  "api_version": "1",
  "problem": {
    "variables": [
      {
        "name": "chairs",
        "lower": 0
      },
      {
        "name": "tables",
        "lower": 0
      }
    ],
    "constraints": [
      {
        "expr": "4*chairs + 8*tables <= 160",
        "name": "machine_hours"
      },
      {
        "expr": "2*chairs + 3*tables <= 75",
        "name": "material"
      }
    ],
    "objective": {
      "sense": "max",
      "expr": "45*chairs + 80*tables"
    }
  },
  "solver": "highs",
  "options": {
    "compute_preset": "cpu-standard",
    "time_limit_seconds": 5,
    "tags": [
      "quickstart"
    ]
  }
}

Ready for the details? Full API reference

Bearer keys

Every request carries your API key as a bearer token. Keys are scoped to the optimisation API, so a leaked key cannot touch anything else in your account.

Authorization: Bearer <your-api-key>

Create your first key in the portal. After that you can list, mint and revoke keys over the API itself (see API keys). Keep keys server-side, and rotate them with no downtime when needed.

The submit envelope

One versioned wrapper around four parts. We own and validate the wrapper; the problem inside is yours.

api_version

The wire version. Always "1" today.

problem

Your model: variables, constraints, an objective. Opaque to us, validated by the solver.

solver

The engine to run: a concrete solver name, or a meta-solver name, which is a named set of member engines, any of which may take the job. Solver tuning travels inside problem.

options

time_limit_seconds, compute_preset, webhook, idempotency_key and tags. All optional.

options.compute_preset

The compute the solve reserves, by code (cpu-standard, gpu-standard). Omit it and the engine runs on its own default. GET /solvers lists every preset and which engines offer which.

{
  "api_version": "1",
  "problem": {
    "variables": [
      {
        "name": "chairs",
        "lower": 0
      },
      {
        "name": "tables",
        "lower": 0
      }
    ],
    "constraints": [
      {
        "expr": "4*chairs + 8*tables <= 160",
        "name": "machine_hours"
      },
      {
        "expr": "2*chairs + 3*tables <= 75",
        "name": "material"
      }
    ],
    "objective": {
      "sense": "max",
      "expr": "45*chairs + 80*tables"
    }
  },
  "solver": "highs",
  "options": {
    "compute_preset": "cpu-standard",
    "time_limit_seconds": 5,
    "tags": [
      "quickstart"
    ]
  }
}

Machine-readable JSON Schemas: admission_request_v1.json

The schema types problem as an opaque object, because the manager never reads it. The section below is the shape the solvers do read.

Describing a model

Three keys inside problem: the variables you decide, the constraints they must respect, and one objective. Expressions are strings, and they are linear.

variables

A list. Each entry needs a name of letters, digits and underscores, not starting with a digit. type is continuous (the default), integer or binary. lower and upper are optional numeric bounds; omit one and the variable is unbounded on that side.

constraints

A list of expr strings, each with an optional name that comes back in the diagnosis. An expr is terms on the left, one number on the right, joined by <=, >= or ==.

objective

sense is min or max; expr uses the same terms with no comparison and no constant. A constant only shifts the value, so it is refused rather than silently dropped.

Terms. A term is a coefficient, an asterisk and a variable name: 4*chairs. A coefficient of one may be written as the name alone. Terms join with a plus or a minus and a space either side: 4*chairs + 8*tables - 2*offcuts. Anything that is not linear is not accepted: no product of two variables, no functions, no exponents.

Declaring a variable integer or binary is what turns a linear program into a mixed-integer one. Nothing else in the envelope changes, and the price is still the base fee plus the seconds. The worked example below is a complete model with five binary variables.

Status and outcome

Two frozen vocabularies. status is the lifecycle of the problem; once it reaches finished, outcome classifies the answer.

Branch on these two fields only. The solution also carries the solver's verbatim MOI termination_status (such as OPTIMAL or TIME_LIMIT) as diagnosis detail; treat it as display text, not a contract.

Idempotency

Set options.idempotency_key to a unique string. If a network blip makes you retry, the second submit returns the original problem instead of creating a duplicate (and a duplicate credit hold).

"options": { "idempotency_key": "order-4821-solve", "time_limit_seconds": 5 }

Keys are scoped to your account. Reusing one always returns the first problem created with it.

Errors

Failures come back with the matching HTTP status and a JSON body. Match on code, show message, and read details when a field is at fault.

{ "error": { "code": "invalid_envelope", "message": "...", "details": {...} } }

Limits and credits

Two things bound your usage: how many solves run at once, and how long each may run.

Concurrency

Your concurrency_cap (see GET /account) is how many problems solve at the same time. Beyond it, new submits wait in the queue.

Credits

A solve costs its engine's base fee plus its rate on the compute preset it runs on, per second. The maximum cost is that rate over the whole of time_limit_seconds, and it is reserved when the problem is admitted; GET /quote answers the same figure before you submit. Settlement bills the seconds actually used, so a run that finishes early costs less and a cancelled one bills what it ran.

Solutions

Retrieve results, one at a time or in bulk.

# 302 to a presigned URL by default; inline=1 returns the body itself.
curl "$BASE/problems/prb_9f3c.../result?inline=1" \
  -H "Authorization: Bearer $API_KEY"

{
  "problem_id": "prb_9f3c...",
  "outcome": "solved",
  "solution": {
    "solver_used": "highs",
    "outcome": "solved",
    "termination_status": "OPTIMAL",
    "objective_value": 1750.0,
    "result": {"values": {"chairs": 30.0, "tables": 5.0}},
    "metering": {"wall_seconds": 0.4}
  }
}

Solvers and account

The engine catalogue and your account state.

curl "$BASE/solvers" -H "Authorization: Bearer $API_KEY"

{
  "solvers": [
    {"name": "highs", "display_name": "HiGHS",
     "description": "LP, MIP", "availability": "ok",
     "pricing": {
       "base_fee": 1, "runtime_rate": 1.0,
       "default_preset": "cpu-standard",
       "presets": [
         {"code": "cpu-standard", "name": "CPU Standard",
          "multiplier": 1.0, "is_default": true,
          "effective_rate": 1.0},
         {"code": "cpu-performance", "name": "CPU Performance",
          "multiplier": 2.5, "is_default": false,
          "effective_rate": 2.5}
       ]}}
  ],
  "compute_presets": [
    {"code": "cpu-standard", "name": "CPU Standard",
     "description": "2 vCPU, 4 GiB memory", "is_gpu": false}
  ]
}

# what a 60 second solve on HiGHS would cost, on the larger CPU preset
curl "$BASE/quote?solver=highs&compute_preset=cpu-performance&time_limit_seconds=60" \
  -H "Authorization: Bearer $API_KEY"

{
  "solver": "highs",
  "compute_preset": "cpu-performance",
  "max_runtime_seconds": 60,
  "max_cost": 151,
  "rates": {"highs": {"base_fee": 1, "effective_rate": 2.5}}
}

curl "$BASE/account" -H "Authorization: Bearer $API_KEY"

{
  "name": "Acme Corp",
  "status": "active",
  "concurrency_cap": 4,
  "credit_balance": 4820,
  "credit_available": 4770
}

Webhooks

Configure and inspect your outbound callbacks. See the Webhooks guide for signatures.

curl "$BASE/account/webhook" -H "Authorization: Bearer $API_KEY"

{
  "url": "https://acme.example/hook",
  "events": ["terminal"],
  "secret_prefix": "whsec_<first 8>"
}

curl -X PUT "$BASE/account/webhook" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://acme.example/hook", "events": ["terminal", "progress"]}'

{
  "url": "https://acme.example/hook",
  "events": ["terminal", "progress"],
  "secret_prefix": "whsec_<first 8>"
}

curl -X POST "$BASE/account/webhook/rotate" \
  -H "Authorization: Bearer $API_KEY"

{
  "url": "https://acme.example/hook",
  "events": ["terminal"],
  "secret_prefix": "whsec_<first 8>",
  "secret": "whsec_<the full secret, shown once>"
}

curl -X POST "$BASE/account/webhook/test" \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "dlv_4c1e...",
  "event_id": "evt_8a02...",
  "type": "test",
  "status": "delivered",
  "attempts": [{"at": "2026-09-18T09:12:04Z", "http_status": 200, "error": null}]
}

curl "$BASE/account/webhook/deliveries" \
  -H "Authorization: Bearer $API_KEY"

{
  "deliveries": [
    {"id": "dlv_4c1e...", "event_id": "evt_8a02...",
     "type": "problem.updated", "problem_id": "prb_a",
     "subscriber": "account", "url": "https://acme.example/hook",
     "status": "dead", "attempts": [{"at": "2026-09-18T09:12:04Z",
       "http_status": 500, "error": "server error"}]}
  ],
  "next_cursor": null
}

curl -X POST "$BASE/account/webhook/deliveries/dlv_4c1e.../retry" \
  -H "Authorization: Bearer $API_KEY"

{"id": "dlv_4c1e...", "status": "pending", "attempts": [...]}

API keys

Manage keys programmatically. The first key is created in the portal.

curl "$BASE/account/keys" -H "Authorization: Bearer $API_KEY"

{
  "keys": [
    {"id": 41, "name": "prod", "prefix": "3f9c1a2b",
     "created_at": "2026-07-01T09:00:00Z", "expires_at": null}
  ]
}

curl -X POST "$BASE/account/keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-2026", "expires_days": 365}'

{"id": 42, "name": "prod-2026", "prefix": "7b2e4f9d",
 "key": "<full key, shown once>"}

curl -X DELETE "$BASE/account/keys/41" \
  -H "Authorization: Bearer $API_KEY"

{"revoked": 41}

Managing API keys

Your first key is created in the portal (you need a key to call the API). After that, manage them over the API so rotation can be automated.

Rotate with no downtime. Create the successor, deploy it, then revoke the old key. Revoking your only key is refused so you cannot lock yourself out.

# Rotate with no downtime: mint the successor, switch over, then revoke.
# 1. Create the replacement (the secret is shown exactly once).
curl -s -X POST "$BASE/account/keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-2026"}'
# -> {"id":42,"name":"prod-2026","prefix":"7b2e4f9d","key":"<full key, shown once>"}

# 2. Deploy the new key everywhere, then revoke the old one by id.
curl -s -X DELETE "$BASE/account/keys/41" -H "Authorization: Bearer $NEW_KEY"
# -> {"revoked": 41}

Python SDK

The envelope is the contract, so the SDK stays a thin convenience over it. Anything jumpy does, your own client can do.