cuopt-server-api-python
cuOpt REST server — start server, endpoints, Python/curl client examples
Install / Use
npx skills add NVIDIA/skills --skill cuopt-server-api-pythonInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of cuopt-server-api-python
cuopt-server-api-python scores 89/100 on our quality scale, 353rd of 745 Operations skills we index (top 48%).
Its SKILL.md is 6.0 KB long, well organised into 17 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
With 3,421 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so cuopt-server-api-python is actively maintained.
- Our last check on 2026-10-31 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
cuopt-server-api-python compared with similar skills
All 4 of these similar skills score higher than cuopt-server-api-python; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| cuopt-server-api-python (this skill)by NVIDIA | 89 | 3.4k | 54d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
| crawl4aiby unclecode | 100 | 87.4k | 3d ago | MCP Server |
Frequently asked questions
- How do I install cuopt-server-api-python?
- Run
npx skills add NVIDIA/skills --skill cuopt-server-api-python. The install tabs above show the steps for each supported agent. - Which AI agents does cuopt-server-api-python work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is cuopt-server-api-python safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is cuopt-server-api-python still maintained?
- The repository was last updated about 2 months ago, so cuopt-server-api-python is actively maintained.
Skill content
View source on GitHubname: cuopt-server-api-python version: "26.10.00" description: cuOpt REST server — start server, endpoints, Python/curl client examples. Use when the user is deploying or calling the REST API. license: Apache-2.0 metadata: author: NVIDIA cuOpt Team tags: - cuopt - server - rest-api - python - deployment
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 allfor Docker). cuopt-serverinstalled, 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:
- Problem type — Routing or LP/MILP? (QP not available via REST.)
- Deployment — Local, Docker, Kubernetes, or cloud?
- Client — Which language or tool will call the API (e.g. Python, curl, another service)?
Start server
# Development
python -m cuopt_server.cuopt_service --ip 0.0.0.0 --port 8000
# Docker — pick the tag matching your CUDA major version
docker run --gpus all -d -p 8000:8000 -e CUOPT_SERVER_PORT=8000 \
nvidia/cuopt:latest-cu13
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
Confirm the server is up by requesting GET /cuopt/health on the local port (e.g. http://localhost:8000/cuopt/health) — a healthy server returns HTTP 200.
Instructions
- POST to
/cuopt/request→ getreqId - Poll
/cuopt/solution/{reqId}until solution ready - 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
import requests, time
SERVER = "http://localhost:8000"
HEADERS = {"Content-Type": "application/json", "CLIENT-VERSION": "custom"}
payload = {
"cost_matrix_data": {"data": {"0": [[0,10,15],[10,0,12],[15,12,0]]}},
"travel_time_matrix_data": {"data": {"0": [[0,10,15],[10,0,12],[15,12,0]]}},
"task_data": {"task_locations": [1, 2], "demand": [[10, 20]], "task_time_windows": [[0,100],[0,100]], "service_times": [5, 5]},
"fleet_data": {"vehicle_locations": [[0, 0]], "capacities": [[50]], "vehicle_time_windows": [[0, 200]]},
"solver_config": {"time_limit": 5}
}
r = requests.post(f"{SERVER}/cuopt/request", json=payload, headers=HEADERS, timeout=30)
req_id = r.json()["reqId"]
# Poll: GET /cuopt/solution/{req_id}
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/ — Basic VRP (no time windows)
- assets/vrp_basic/ — VRP with time windows
- assets/pdp_basic/ — Pickup and delivery
- assets/lp_basic/ — LP via REST (CSR format)
- assets/milp_basic/ — MILP via REST
See assets/README.md for overview.
Escalate
For contribution or build-from-source, see the developer skill.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.4kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
