Cuopt Server API Python

NVIDIAOfficialCreated by NVIDIA cuOpt Team

Skill
Tool integration
Software development
Apache-2.0
Medium risk
Has scripts

From the author

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

— the description by NVIDIA cuOpt Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides instructions for deploying the cuOpt REST server and integrating it into applications using Python or curl. It covers server startup procedures for local and Docker environments, the asynchronous request-polling pattern required for job submission, and guidance on mapping problem data to REST API endpoints. It also includes troubleshooting steps for common payload and deployment issues.

What it does

Provides commands to start the cuOpt REST server locally or via Docker.
Explains the asynchronous request-polling workflow for job submission and solution retrieval.
Maps Python API concepts to REST API field names and structures.
Offers troubleshooting guidance for common HTTP errors and payload formatting issues.
Provides examples for routing, LP, and MILP problem types.
Outlines security considerations for the unauthenticated REST interface.

When to use it

When deploying the cuOpt server in a production or development environment.
When building a client application to interface with cuOpt via HTTP.
When debugging rejected payloads or 422 errors during API interaction.
When transitioning from the Python library to a REST-based architecture.

Advantages

Language-agnostic API allows integration with any service capable of making HTTP requests.
Standardized polling pattern for handling long-running optimization tasks.
Clear mapping between Python API and REST schema reduces implementation friction.
Comprehensive troubleshooting table addresses common deployment and payload errors.

Usage examples

“How do I start the cuOpt server using Docker?”: The agent provides the docker run command with the necessary GPU flags and port mappings, including advice on using specific version tags.
“I am getting a 422 error when sending fleet data to the cuOpt API.”: The agent explains the correct nesting for capacity dimensions and provides a corrected JSON structure example.
“How do I retrieve a solution after posting a request to the cuOpt server?”: The agent outlines the polling loop pattern, showing how to use the reqId to query the /cuopt/solution endpoint until the task is complete.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/nvidia/cuopt-server-api-python/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip cuopt-server-api-python.zip -d .agents/skills

Documentation by NVIDIA cuOpt Team

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:

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).

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>-cu<cuda-major>) 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 → get reqId
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 Content`	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.

Files

ATTRIBUTION.mdAdded by AutoGineer938 B
BENCHMARK.md8.8 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md5.8 KiB
assets/README.md608 B
assets/lp_basic/README.md368 B
assets/lp_basic/client.pyScript2.9 KiB
assets/milp_basic/README.md360 B
assets/milp_basic/client.pyScript2.8 KiB
assets/pdp_basic/README.md287 B
assets/pdp_basic/client.pyScript3.3 KiB
assets/vrp_basic/README.md376 B
assets/vrp_basic/client.pyScript3.5 KiB
assets/vrp_simple/README.md254 B
assets/vrp_simple/client.pyScript3.2 KiB
evals/evals.json8.5 KiB
skill-card.md4.2 KiB
skill.oms.sig7.0 KiB

BENCHMARK.md

Skill Benchmark: cuopt-server-api-python

✅ Overall verdict: PASS — Recommended for publication

Publication Recommendation

Recommended for publication based on the completed evaluation evidence in this report.

Evaluation Metadata

Skill: cuopt-server-api-python
Evaluation date: 2026-10-16
Evaluator version: 1.5.6
Agents: Claude Code (aws/anthropic/bedrock-claude-opus-4-8), Codex (openai/openai/gpt-5.5)
Tasks: 8 evaluation tasks (8 positive)
Dataset digest: sha256:c54a53a22db535b2e2101bfcd2c43a8cdfef342f5c166ba343b8fdba517c741d (skill-evaluator-dataset-snapshot/1)
Attempts per task: 1
Environment: k8s-sandbox
Tier 2 evidence: required for publication
Tier 3 evidence: required for publication

Each task attempt ran in its own isolated sandbox pod.

What This Report Answers

The three-tier evaluation checks whether the skill:

is safe to use;
produces correct answers;
is discovered and activated when needed;
helps the agent complete the user's goal and expected workflow; and
avoids wasted skill and tool usage.

Results at a Glance

Measure	Claude Code (Baseline → Skill Uplift)	Codex (Baseline → Skill Uplift)
Overall	98.3% — baseline ran, but no comparable score was available; uplift unavailable	95.9% — baseline ran, but no comparable score was available; uplift unavailable
Security	100.0% → 100.0% (±0.0 points)	100.0% → 100.0% (±0.0 points)
Correctness	77.5% → 100.0% (+22.5 points)	82.5% → 100.0% (+17.5 points)
Discoverability	100.0% — baseline ran, but no comparable score was available; uplift unavailable	93.8% — baseline ran, but no comparable score was available; uplift unavailable
Effectiveness	58.1% → 94.3% (+36.2 points)	64.1% → 90.5% (+26.4 points)
Efficiency	97.1% — baseline ran, but no comparable score was available; uplift unavailable	95.1% — baseline ran, but no comparable score was available; uplift unavailable

How to read this table: baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.

Example: 47.0% → 92.0% (+45.0 points) means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.

Token Usage

Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.

Agent	Dataset case	With skill	Without skill	Delta	Change	Coverage
claude-code	All cases	885,077	597,044	+288,033	+48.24%	skill 8/8; base 8/8
claude-code	srv-py-eval-001-rest-routing-workflow	61,314	29,004	+32,310	+111.40%	skill 1/1; base 1/1
claude-code	srv-py-eval-002-rest-lp-payload-fields	158,831	29,008	+129,823	+447.54%	skill 1/1; base 1/1
claude-code	srv-py-eval-003-rest-milp-vs-lp	159,973	28,976	+130,997	+452.09%	skill 1/1; base 1/1
claude-code	srv-py-eval-004-qp-not-supported-over-rest	60,627	59,196	+1,431	+2.42%	skill 1/1; base 1/1
claude-code	srv-py-eval-005-debug-422-field-names	60,837	29,007	+31,830	+109.73%	skill 1/1; base 1/1
claude-code	srv-py-eval-006-docker-deployment	60,693	28,988	+31,705	+109.37%	skill 1/1; base 1/1
claude-code	srv-py-eval-007-client-hardening	162,999	28,980	+134,019	+462.45%	skill 1/1; base 1/1
claude-code	srv-py-eval-008-runnable-assets	159,803	363,885	-204,082	-56.08%	skill 1/1; base 1/1
codex	All cases	388,941	481,460	-92,519	-19.22%	skill 8/8; base 8/8
codex	srv-py-eval-001-rest-routing-workflow	45,413	92,911	-47,498	-51.12%	skill 1/1; base 1/1
codex	srv-py-eval-002-rest-lp-payload-fields	45,088	46,097	-1,009	-2.19%	skill 1/1; base 1/1
codex	srv-py-eval-003-rest-milp-vs-lp	45,998	30,983	+15,015	+48.46%	skill 1/1; base 1/1
codex	srv-py-eval-004-qp-not-supported-over-rest	28,544	46,936	-18,392	-39.19%	skill 1/1; base 1/1
codex	srv-py-eval-005-debug-422-field-names	28,579	61,511	-32,932	-53.54%	skill 1/1; base 1/1
codex	srv-py-eval-006-docker-deployment	35,800	32,176	+3,624	+11.26%	skill 1/1; base 1/1
codex	srv-py-eval-007-client-hardening	79,361	27,750	+51,611	+185.99%	skill 1/1; base 1/1
codex	srv-py-eval-008-runnable-assets	80,158	143,096	-62,938	-43.98%	skill 1/1; base 1/1
ALL AGENTS	Dataset aggregate	1,274,018	1,078,504	+195,514	+18.13%	skill 16/16; base 16/16

Prompt tokens include cached reads, so total tokens are prompt + completion (cached is not added twice). The Efficiency score uses (prompt - cached) + completion. N/A means the relevant trajectory counters were not available; coverage is never estimated.

Tier Status

Tier	Purpose	Status	Evidence
Tier 1	Static validation	PASSED WITH OBSERVATIONS	11 validator(s); 16 finding(s)
Tier 2	Semantic deduplication	PASSED	2 validator(s); 0 finding(s)
Tier 3	Live agent evaluation	PASS	2 agent(s); 8 task(s)

Findings and Observations

<details> <summary>Show detailed findings and successful checks</summary>

MEDIUM SCHEMA/frontmatter_field_placement: Root field 'version' is ignored; use 'metadata.version' (skills/cuopt-server-api-python/SKILL.md)
MEDIUM SECURITY/Unknown (LP3): MCP Least Privilege: The skill demonstrates network-capable code (HTTP requests via requests, Docker networking) but declares no tool scope (SKILL.md:1)
MEDIUM SECURITY/Unknown (RP1): MCP Rug Pull: The Docker run command uses nvidia/cuopt:latest-cu13 (a floating/mutable tag). The skill itself acknowledges this risk (SKILL.md:55)
MEDIUM SECURITY/External Transmission (E1): Data Exfiltration: requests.post(f"{SERVER}/cuopt/request", json= (SKILL.md:88)
MEDIUM SECURITY/Tainted flow: 'req_id' from requests.post (line 81, network input) → requests.get (network output) (TT2): Data Flow: response = requests.get( f"{server}/cuopt/solution/{req_id}", headers=HEADERS, timeout=REQUEST_TIMEOUT, ) (assets/lp_basic/client.py:88)
11 additional finding(s) are available in the full evaluation artifacts.

</details>

Scoring Methodology

<details> <summary>Show dimension definitions, source signals, and thresholds</summary>

Dimension	Question	Scored signals
Security	Is it safe to use?	`security` (100%)
Correctness	Is the answer correct?	`accuracy` (100%)
Discoverability	Was the right skill loaded when needed?	`skill_execution` (100%)
Effectiveness	Did the skill help complete the task?	`goal_accuracy` (50%) + `behavior_check` (50%)
Efficiency	Did it avoid wasted tool calls and token usage?	`skill_efficiency` (50%) + `token_efficiency` (50%)

Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.
Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.
Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.
The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.
Effectiveness is the equal-weight mean of goal completion (goal_accuracy) and expected workflow adherence (behavior_check).
Efficiency is 50% tool-call productivity (the backward-compatible skill_efficiency wire id) and 50% token_efficiency. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.

Signals present in this run:

security (Security): unsafe operations, secret leakage, and unauthorized access.
skill_execution (Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.
skill_efficiency (Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).
accuracy (Accuracy): final-answer correctness against the reference answer.
goal_accuracy (Goal Accuracy): whether the user's goal was achieved.
behavior_check (Behavior Check): whether the expected workflow behavior was followed.
token_efficiency (Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).

</details>

Freshness

Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs network access, Needs an API key, Needs a command-line tool, Needs Python

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA cuOpt Team

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/cuopt-server-api-python · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by NVIDIA cuOpt Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cuopt-server-api-python.zip