De NexOR Optimization API

Uw eerste solve, in drie stappen

Van nul naar een echt antwoord in enkele minuten. Een productiemix met twee producten: maximaliseer de marge binnen limieten op machine-uren en materiaal. Het optimum is 30 stoelen en 5 tafels, doelfunctiewaarde 1750.

1. Kopieer een API-sleutel

   Geef hem een naam en kies een vervaldatum, meer stelt het formulier niet voor. Deze sleutel identificeert u bij elke API-call die u doet. Het geheim wordt maar één keer getoond, kopieer het dus meteen. Dit is de enige stap die in de browser gebeurt.

   API-sleutels openen

2. Indienen, wachten, ophalen

   Plak uw sleutel in het voorbeeld hieronder en voer het uit: dien de envelope in, houd één aanvraag open tot het probleem klaar is, en haal dan de oplossing op. Dat is de kortste weg vanaf een laptop, waar niets een webhook kan ontvangen. Zodra u een server draait, registreer een webhook en laat de middelste stap vallen.

# 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"
    ]
  }
}

Klaar voor de details? Volledige API-referentie

Bearer-sleutels

Elke aanvraag draagt uw API-sleutel als bearer-token. Sleutels zijn afgebakend tot de optimalisatie-API, dus een gelekte sleutel kan niets anders in uw account raken.

Authorization: Bearer <your-api-key>

Maak uw eerste sleutel aan in het portaal. Daarna kunt u sleutels oplijsten, aanmaken en intrekken via de API zelf (zie API-sleutels). Bewaar sleutels server-side en roteer ze zonder downtime wanneer nodig.

De inzendingsenvelope

Eén geversioneerde wrapper rond vier onderdelen. Wij beheren en valideren de wrapper; het problem erin is van u.

api_version

De wire-versie. Vandaag altijd "1".

problem

Uw model: variabelen, beperkingen, een doelfunctie. Opaak voor ons, gevalideerd door de solver.

solver

De solver die moet draaien: een concrete solvernaam, of de naam van een meta-solver, dat is een benoemde set solvers waarvan om het even welke de opdracht kan opnemen. Solverinstellingen reizen mee binnen problem.

options

time_limit_seconds, compute_preset, webhook, idempotency_key en tags. Allemaal optioneel.

options.compute_preset

De rekenkracht die de solve reserveert, per code (cpu-standard, gpu-standard). Laat u het weg, dan draait de solver op zijn eigen standaardprofiel. GET /solvers lijst elk profiel op en welke solvers het aanbieden.

{
  "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"
    ]
  }
}

Machineleesbare JSON-schema's: admission_request_v1.json

Het schema typeert problem als een opaak object, want de manager leest het nooit. De sectie hieronder is de vorm die de solvers wel lezen.

Een model beschrijven

Drie sleutels binnen problem: de variabelen waarover u beslist, de constraints die ze moeten respecteren, en één doelfunctie. Expressies zijn strings, en ze zijn lineair.

variables

Een lijst. Elk item heeft een name nodig van letters, cijfers en underscores, niet beginnend met een cijfer. type is continuous (de standaard), integer of binary. lower en upper zijn optionele numerieke grenzen; laat er één weg en de variabele is aan die kant onbegrensd.

constraints

Een lijst van expr-strings, elk met een optionele name die terugkomt in de diagnose. Een expr is termen links, één getal rechts, verbonden door <=, >= of ==.

objective

sense is min of max; expr gebruikt dezelfde termen, zonder vergelijking en zonder constante. Een constante verschuift alleen de waarde, dus wordt ze geweigerd in plaats van stil weggelaten.

Termen. Een term is een coëfficiënt, een sterretje en een variabelenaam: 4*chairs. Een coëfficiënt van één mag u schrijven als de naam alleen. Termen worden verbonden met een plus of een min en een spatie aan weerszijden: 4*chairs + 8*tables - 2*offcuts. Wat niet lineair is, wordt niet aanvaard: geen product van twee variabelen, geen functies, geen exponenten.

Een variabele integer of binary verklaren is wat een lineair programma in een gemengd geheeltallig programma verandert. Verder verandert er niets in de envelope, en de prijs blijft het basistarief plus de seconden. De uitgewerkt voorbeeld hieronder staat een volledig model met vijf binaire variabelen.

Status en uitkomst

Twee vaste woordenlijsten. status is de levenscyclus van het probleem; zodra het finished bereikt, duidt outcome het antwoord.

Vertak enkel op deze twee velden. De oplossing bevat ook de letterlijke MOI termination_status van de solver (zoals OPTIMAL of TIME_LIMIT) als diagnosedetail; behandel die als weergavetekst, niet als contract.

Idempotentie

Stel options.idempotency_key in op een unieke string. Als u door een netwerkhapering opnieuw indient, geeft de tweede submit het oorspronkelijke probleem terug in plaats van een duplicaat aan te maken (en een dubbele kredietreservering).

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

Sleutels zijn gebonden aan uw account. Een sleutel hergebruiken geeft altijd het eerste probleem terug dat ermee werd aangemaakt.

Fouten

Fouten komen terug met de passende HTTP-status en een JSON-body. Match op code, toon message en lees details wanneer een veld in fout is.

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

Limieten en credits

Twee dingen begrenzen uw gebruik: hoeveel solves tegelijk draaien, en hoe lang elk mag draaien.

Gelijktijdigheid

Uw concurrency_cap (zie GET /account) bepaalt hoeveel problemen tegelijk opgelost worden. Daarboven wachten nieuwe submits in de wachtrij.

Credits

Een solve kost het basistarief van zijn solver plus zijn tarief op het rekenprofiel waarop hij draait, per seconde. De maximale kost is dat tarief over de volledige time_limit_seconds, en wordt gereserveerd zodra het probleem toegelaten is; GET /quote geeft hetzelfde cijfer vóór u indient. De afrekening factureert de werkelijk gebruikte seconden, dus een run die vroeger klaar is kost minder en een geannuleerde run factureert wat ze gedraaid heeft.

Oplossingen

Haal resultaten op, één per één of 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 en account

De solvercatalogus en de staat van uw account.

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

Configureer en inspecteer uw uitgaande callbacks. Zie de webhookgids voor de handtekeningen.

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-sleutels

Beheer sleutels programmatisch. De eerste sleutel maakt u aan in het portaal.

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}

API-sleutels beheren

Uw eerste sleutel maakt u aan in het portaal (u hebt een sleutel nodig om de API aan te roepen). Daarna beheert u ze via de API, zodat rotatie geautomatiseerd kan worden.

Roteer zonder downtime. Maak de opvolger aan, rol die uit en trek daarna de oude sleutel in. Uw enige sleutel intrekken wordt geweigerd, zodat u zichzelf niet kunt buitensluiten.

# 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

De envelope is het contract, dus blijft de SDK een dunne gemakslaag erbovenop. Alles wat jumpy kan, kan uw eigen client ook.