/cuopt-server-api-python

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

nvidia@nvidia

GitHub

From plugin

nvidia-skills

2.8k200 skills3 agents

Install

$ npx -y skills add NVIDIA/skills --skill cuopt-server-api-python --agent claude-code

How it fires

How this skill gets triggered: by you, by Claude, or both.

Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/cuopt-server-api-python

Context preview

The summary Claude sees to decide when to auto-load this skill.

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

SKILL.md

cuopt-server-api-python.SKILL.md

name: cuopt-server-api-python
version: "26.08.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).

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

# Development
python -m cuopt_server.cuopt_service --ip 0.0.0.0 --port 8000

# Docker
docker run --gpus all -d -p 8000:8000 -e CUOPT_SERVER_PORT=8000 \
  nvidia/cuopt:latest-cuda12.9-py3.13

Verify

curl http://localhost:8000/cuopt/health

Workflow

1. POST to `/cuopt/request` → get `reqId` 2. Poll `/cuopt/solution/{reqId}` until solution ready 3. Parse response

Python client (routing)

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

Debugging (422 / payload)

**Validation errors:** Check field names against OpenAPI (`/cuopt.yaml`). Common mistakes: `transit_time_matrix_data` → `travel_time_matrix_data`; capacities per dimension `[[50, 50]]` not per vehicle `[[50], [50]]`. Capture `reqId` and response body for failed requests.