L'API NexOR Optimization

Votre première résolution, en trois étapes

De zéro à une vraie réponse en quelques minutes. Un mix de production à deux produits : maximiser la marge sous des limites d'heures machine et de matières. L'optimum est de 30 chaises et 5 tables, objectif 1750.

1. Copier une clé API

   Donnez-lui un nom, choisissez une expiration, c'est tout le formulaire. Cette clé vous identifie à chaque appel API que vous faites. Le secret ne s'affiche qu'une fois, copiez-le tout de suite. C'est la seule étape qui se passe dans le navigateur.

   Ouvrir les clés API

2. Soumettre, attendre, récupérer

   Collez votre clé dans l'exemple ci-dessous et exécutez-le : soumettez l'enveloppe, gardez une requête ouverte jusqu'à la fin du problème, puis récupérez la solution. C'est le chemin le plus court depuis un portable, où rien ne peut recevoir un webhook. Dès que vous avez un serveur, enregistrez un webhook et supprimez l'étape du milieu.

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

Prêt pour les détails ? Référence d'API complète

Clés porteuses

Chaque requête porte votre clé API comme jeton porteur. Les clés sont cantonnées à l'API d'optimisation : une clé qui fuit ne peut toucher à rien d'autre dans votre compte.

Authorization: Bearer <your-api-key>

Créez votre première clé dans le portail. Ensuite, vous pouvez lister, créer et révoquer les clés via l'API elle-même (voir Clés API). Gardez vos clés côté serveur et faites-en la rotation sans interruption quand c'est nécessaire.

L'enveloppe de soumission

Une enveloppe versionnée autour de quatre parties. Nous possédons et validons l'enveloppe ; le problem à l'intérieur vous appartient.

api_version

La version du protocole. Toujours "1" aujourd'hui.

problem

Votre modèle : variables, contraintes, un objectif. Opaque pour nous, validé par le solveur.

solver

Le moteur à exécuter : un nom de solveur concret, ou un nom de méta-solveur, c'est-à-dire un ensemble nommé de moteurs membres dont n'importe lequel peut prendre le travail. Le réglage du solveur voyage à l'intérieur de problem.

options

time_limit_seconds, compute_preset, webhook, idempotency_key et tags. Tous facultatifs.

options.compute_preset

Le calcul que la résolution réserve, par code (cpu-standard, gpu-standard). Omettez-le et le moteur tourne sur son profil par défaut. GET /solvers liste tous les profils et les moteurs qui les proposent.

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

Schémas JSON lisibles par machine : admission_request_v1.json

Le schéma type problem comme un objet opaque, parce que le manager ne le lit jamais. La section ci-dessous décrit la forme que les solveurs, eux, lisent.

Décrire un modèle

Trois clés dans problem : les variables que vous décidez, les contraintes qu'elles doivent respecter, et un objectif. Les expressions sont des chaînes, et elles sont linéaires.

variables

Une liste. Chaque entrée a besoin d'un name composé de lettres, de chiffres et de tirets bas, ne commençant pas par un chiffre. type vaut continuous (par défaut), integer ou binary. lower et upper sont des bornes numériques optionnelles ; omettez-en une et la variable est non bornée de ce côté.

constraints

Une liste de chaînes expr, chacune avec un name optionnel qui revient dans le diagnostic. Un expr, ce sont des termes à gauche, un nombre à droite, joints par <=, >= ou ==.

objective

sense vaut min ou max ; expr reprend les mêmes termes, sans comparaison ni constante. Une constante ne fait que décaler la valeur : elle est refusée plutôt que supprimée en silence.

Termes. Un terme est un coefficient, un astérisque et un nom de variable : 4*chairs. Un coefficient égal à un peut s'écrire par le nom seul. Les termes se joignent par un plus ou un moins entouré d'espaces : 4*chairs + 8*tables - 2*offcuts. Tout ce qui n'est pas linéaire est refusé : pas de produit de deux variables, pas de fonctions, pas d'exposants.

Déclarer une variable integer ou binary, c'est ce qui transforme un programme linéaire en programme mixte en nombres entiers. Rien d'autre ne change dans l'enveloppe, et le prix reste les frais de base plus les secondes. Un exemple commenté complet, à cinq variables binaires, figure ci-dessous.

Statut et résultat

Deux vocabulaires figés. status est le cycle de vie du problème ; une fois qu'il atteint finished, outcome qualifie la réponse.

Branchez votre logique sur ces deux champs uniquement. La solution porte aussi, tel quel, le termination_status MOI du solveur (comme OPTIMAL ou TIME_LIMIT) comme détail de diagnostic. Traitez-le comme du texte d'affichage, pas comme un contrat.

Idempotence

Définissez options.idempotency_key sur une chaîne unique. Si un incident réseau vous fait réessayer, la seconde soumission renvoie le problème d'origine au lieu de créer un doublon (et une provision de crédits en double).

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

Les clés sont limitées à votre compte. En réutiliser une renvoie toujours le premier problème créé avec elle.

Erreurs

Les échecs reviennent avec le statut HTTP correspondant et un corps JSON. Branchez-vous sur code, affichez message et lisez details quand un champ est en cause.

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

Limites et crédits

Deux choses bornent votre usage : combien de résolutions tournent en même temps, et combien de temps chacune peut tourner.

Concurrence

Votre concurrency_cap (voir GET /account) est le nombre de problèmes résolus en même temps. Au-delà, les nouvelles soumissions attendent dans la file.

Crédits

Une résolution coûte les frais de base de son moteur plus son tarif sur le profil de calcul où elle tourne, à la seconde. Le coût maximum, c'est ce tarif sur la totalité de time_limit_seconds, et il est réservé quand le problème est admis ; GET /quote donne le même chiffre avant que vous ne soumettiez. Le règlement facture les secondes réellement utilisées : une exécution qui se termine plus tôt coûte moins, et une exécution annulée facture ce qu'elle a tourné.

Solutions

Récupérez les résultats, un par un ou en lot.

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

Solveurs et compte

Le catalogue des moteurs et l'état de votre compte.

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

Configurez et inspectez vos rappels sortants. Voir le guide Webhooks pour les 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": [...]}

Clés API

Gérez les clés par programme. La première clé se crée dans le portail.

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}

Gérer les clés API

Votre première clé se crée dans le portail (il faut une clé pour appeler l'API). Ensuite, gérez-les via l'API pour automatiser la rotation.

Rotation sans interruption. Créez la nouvelle clé, déployez-la, puis révoquez l'ancienne. Révoquer votre unique clé est refusé : impossible de vous enfermer dehors.

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

SDK Python

L'enveloppe est le contrat, le SDK reste donc une fine couche de confort par-dessus. Tout ce que jumpy fait, votre propre client peut le faire.