cuOpt REST server — start server, endpoints, Python/curl client examples. Use when the user is deploying or calling the REST API.

cuOpt Server — Deploy and client (Python/curl) This skill covers starting the server and client examples (curl, Python). Server has no separate C API (clients can be any language). Purpose Use this skill when the user is deploying the cuOpt REST server or writing a client against it — choosing a deployment target, mapping a problem onto the HTTP endpoints, translating between Python API and REST field names, or debugging a rejected payload. Prerequisites An NVIDIA GPU with a working CUDA driver (the server requires one; gpus all for Docker). cuopt server installed, or Docker with the NVIDIA Container Toolkit. See the install skill. Python clients need requests . No API key or auth token is required by the server itself. Problem types supported Problem type Supported : : Routing ✓ LP ✓ MILP ✓ QP ✗ Required questions Ask these if not already clear: 1. Problem type — Routing or LP/MILP? (QP not available via REST.) 2. Deployment — Local, Docker, Kubernetes, or cloud? 3. Client — Which language or tool will call the API (e.g. Python, curl, another service)? Start server Use latest cu12 or latest cu13 to match your driver's CUDA major version ( latest cu13 ubi10 for a UBI10 base). Prefer these over the CUDA+Python specific tags such as latest cuda12.9 py3.13 — those track a single Python line and go stale when it stops receiving builds. For production, pin rather than float: latest tags are mutable and can silently move to a different image. Use a full release tag ( nvidia/cuopt:<release cuda<cuda py<python ) or an immutable digest ( nvidia/cuopt@sha256:<digest ). Check the nvidia/cuopt registry for available tags. Verify Instructions 1. POST to /cuopt/request → get reqId 2. Poll /cuopt/solution/{reqId} until solution ready 3. Parse response Treat reqId as untrusted input: validate it (e.g. re.fullmatch(r"[A Za z0 9 ]{1,64}", req id) ) before interpolating it into the polling URL, and set an explicit timeout on every request. Examples Terminology: REST vs Python API Python API REST order locations task locations set order time windows() task time windows service times service times Use travel time matrix data (not transit time matrix data). Capacities: [[50, 50]] not [[50], [50]] . Troubleshooting Error Cause Solution 422 Unprocessable Entity Field name not in the schema Check names against the OpenAPI spec at /cuopt.yaml . Most common: transit time matrix data → travel time matrix data 422 on fleet data Capacities nested per vehicle instead of per dimension Use [[50, 50]] (one inner list per capacity dimension), not [[50], [50]] Connection refused Server not up, or bound to a different interface/port curl http://localhost:8000/cuopt/health ; start with ip 0.0.0.0 port 8000 Docker container exits immediately No GPU visible to the container Run with gpus all and confirm the NVIDIA Container Toolkit is installed Polling never returns a solution Solve exceeds the client's poll budget Raise solver config.time limit and the poll loop count together Capture the reqId and the full response body for any failed request — both are needed to diagnose server side rejections. Limitations QP is not exposed over REST. Use the Python or C API for quadratic objectives. The server ships no authentication or TLS. Anything that can reach the port can submit jobs. Put it behind a gateway and treat server /base URLs as trusted network endpoints only. Solutions are retrieved by polling; there is no push/webhook delivery. One request is solved at a time per server process; concurrency requires multiple replicas. Runnable assets Run from each asset directory (server must be running; scripts exit 0 if server unreachable). All use Python requests and accept server (default http://localhost:8000 ): [assets/vrp simple/](assets/vrp simple/) — Basic VRP (no time windows) [assets/vrp basic/](assets/vrp basic/) — VRP with time windows [assets/pdp basic/](assets/pdp basic/) — Pickup and delivery [assets/lp basic/](assets/lp basic/) — LP via REST (CSR format) [assets/milp basic/](assets/milp basic/) — MILP via REST See [assets/README.md](assets/README.md) for overview. Escalate For contribution or build from source, see the developer skill.

cuopt-server-api-python