Server API Reference

Note

This API reference documents the internal API for the cuOpt server that is part of the cuOpt Managed Service. It is intended to support development and to provide insight into the format for cuOpt problem data sumbitted to the cuOpt Managed Service.

Additional information on the endpoints and specs can be found here.

GET /cuopt/health

Health

To ping if server is running

Example request:

GET /cuopt/health HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  Successful Response

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {}
  

GET /v2/health/ready

Ready

To check readiness of the server

Example request:

GET /v2/health/ready HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  Successful Response

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {}
  

GET /v2/health/live

Live

To check liveness of the server

Example request:

GET /v2/health/live HTTP/1.1
Host: example.com

Status Codes:

• 200 OK –

  Successful Response

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {}
  

POST /cuopt/routes

Get routes on-prem

Note: This is for self hosted. Takes all the data and options at once, solves the routing problem and returns result.

Query Parameters:

• validation_only ({'null', 'boolean'}) – If set to True, input will be validated, if input is valid, returns a successful message, else returns an error.

Example request:

POST /cuopt/routes HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "cost_waypoint_graph_data": {
        "waypoint_graph": {}
    },
    "travel_time_waypoint_graph_data": {
        "waypoint_graph": {}
    },
    "cost_matrix_data": {
        "data": {},
        "cost_matrix": {}
    },
    "travel_time_matrix_data": {
        "data": {},
        "cost_matrix": {}
    },
    "fleet_data": {
        "vehicle_locations": [
            [
                1
            ]
        ],
        "vehicle_ids": [
            "string"
        ],
        "capacities": [
            [
                1
            ]
        ],
        "vehicle_time_windows": [
            [
                1
            ]
        ],
        "vehicle_break_time_windows": [
            [
                [
                    1
                ]
            ]
        ],
        "vehicle_break_durations": [
            [
                1
            ]
        ],
        "vehicle_break_locations": [
            1
        ],
        "vehicle_types": [
            1
        ],
        "vehicle_order_match": [
            {
                "vehicle_id": 1,
                "order_ids": [
                    1
                ]
            }
        ],
        "skip_first_trips": [
            true
        ],
        "drop_return_trips": [
            true
        ],
        "min_vehicles": 1,
        "vehicle_max_costs": [
            1.0
        ],
        "vehicle_max_times": [
            1.0
        ],
        "vehicle_fixed_costs": [
            1.0
        ]
    },
    "task_data": {
        "task_locations": [
            1
        ],
        "task_ids": [
            "string"
        ],
        "demand": [
            [
                1
            ]
        ],
        "pickup_and_delivery_pairs": [
            [
                1
            ]
        ],
        "task_time_windows": [
            [
                1
            ]
        ],
        "service_times": [
            1
        ],
        "prizes": [
            1.0
        ],
        "order_vehicle_match": [
            {
                "order_id": 1,
                "vehicle_ids": [
                    1
                ]
            }
        ]
    },
    "solver_config": {
        "time_limit": 1.0,
        "objectives": {
            "cost": 1.0,
            "travel_time": 1.0,
            "variance_route_size": 1.0,
            "variance_route_service_time": 1.0,
            "prize": 1.0,
            "vehicle_fixed_cost": 1.0
        },
        "config_file": "string",
        "verbose_mode": true,
        "error_logging": true
    }
}

Status Codes:

• 200 OK –

  Successful Response

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "reqId": "string"
  }
  

• 400 Bad Request –

  Value Error Or Validation Error

  Example response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 409 Conflict –

  Failed to get route

  Example response:

  HTTP/1.1 409 Conflict
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 422 Unprocessable Entity –

  Unprocessable Entity or Runtime Error or Out of memory error

  Example response:

  HTTP/1.1 422 Unprocessable Entity
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 500 Internal Server Error –

  Any uncaught cuOpt error or Server errors

  Example response:

  HTTP/1.1 500 Internal Server Error
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

Request Headers:

• CUOPT-DATA-FILE – Name of data file to process in the server’s CUOPT_DATA_DIR when using the local file feature

• CUOPT-RESULT-FILE – Result file name if output dir is enabled and size >= maxresult

• CLIENT-VERSION – cuOpt client version. Set to ‘custom’ to skip version check

• RESULT-TIMEOUT – Optional timeout. If not specified, the call will be synchronous. If specified and a solution is not found before the timeout expires, a request id will be returned which can be polled for a result.

POST /cuopt/cuopt

Managed Service Endpoint

Note: This is for managed service. Takes all the data and options at once, solves the routing problem and returns result.

Example request:

POST /cuopt/cuopt HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "action": "cuOpt_OptimizedRouting",
    "data": {
        "cost_waypoint_graph_data": {
            "waypoint_graph": {}
        },
        "travel_time_waypoint_graph_data": {
            "waypoint_graph": {}
        },
        "cost_matrix_data": {
            "data": {},
            "cost_matrix": {}
        },
        "travel_time_matrix_data": {
            "data": {},
            "cost_matrix": {}
        },
        "fleet_data": {
            "vehicle_locations": [
                [
                    1
                ]
            ],
            "vehicle_ids": [
                "string"
            ],
            "capacities": [
                [
                    1
                ]
            ],
            "vehicle_time_windows": [
                [
                    1
                ]
            ],
            "vehicle_break_time_windows": [
                [
                    [
                        1
                    ]
                ]
            ],
            "vehicle_break_durations": [
                [
                    1
                ]
            ],
            "vehicle_break_locations": [
                1
            ],
            "vehicle_types": [
                1
            ],
            "vehicle_order_match": [
                {
                    "vehicle_id": 1,
                    "order_ids": [
                        1
                    ]
                }
            ],
            "skip_first_trips": [
                true
            ],
            "drop_return_trips": [
                true
            ],
            "min_vehicles": 1,
            "vehicle_max_costs": [
                1.0
            ],
            "vehicle_max_times": [
                1.0
            ],
            "vehicle_fixed_costs": [
                1.0
            ]
        },
        "task_data": {
            "task_locations": [
                1
            ],
            "task_ids": [
                "string"
            ],
            "demand": [
                [
                    1
                ]
            ],
            "pickup_and_delivery_pairs": [
                [
                    1
                ]
            ],
            "task_time_windows": [
                [
                    1
                ]
            ],
            "service_times": [
                1
            ],
            "prizes": [
                1.0
            ],
            "order_vehicle_match": [
                {
                    "order_id": 1,
                    "vehicle_ids": [
                        1
                    ]
                }
            ]
        },
        "solver_config": {
            "time_limit": 1.0,
            "objectives": {
                "cost": 1.0,
                "travel_time": 1.0,
                "variance_route_size": 1.0,
                "variance_route_service_time": 1.0,
                "prize": 1.0,
                "vehicle_fixed_cost": 1.0
            },
            "config_file": "string",
            "verbose_mode": true,
            "error_logging": true
        }
    },
    "parameters": {},
    "client_version": "string"
}

Status Codes:

• 200 OK –

  Successful Response

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {}
  

• 400 Bad Request –

  Value Error Or Validation Error

  Example response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 409 Conflict –

  Failed to get route

  Example response:

  HTTP/1.1 409 Conflict
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 422 Unprocessable Entity –

  Unprocessable Entity or Runtime Error or Out of memory error

  Example response:

  HTTP/1.1 422 Unprocessable Entity
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 500 Internal Server Error –

  Any uncaught cuOpt error or Server errors

  Example response:

  HTTP/1.1 500 Internal Server Error
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

Request Headers:

• NVCF-ASSET-DIR – Path to asset

• NVCF-FUNCTION-ASSET-IDS – asset id

• NVCF-LARGE-OUTPUT-DIR – Path for large results

• NVCF-NCAID – NVIDIA Cloud Account identifier

• NVCF-REQID – NVCF request id

• NVCF-INSTANCETYPE – host instance type

• NVCF-REGION – host region

• NVCF-ENV – NVCF environment (stage or production)

• NVCF-MAX-RESPONSE-SIZE-BYTES – Max size of direct response from NVCF

POST /cuopt/routes

Get routes on-prem

Note: This is for self hosted. Takes all the data and options at once, solves the routing problem and returns result.

Query Parameters:

• validation_only ({'null', 'boolean'}) – If set to True, input will be validated, if input is valid, returns a successful message, else returns an error.

Example request:

POST /cuopt/routes HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "cost_waypoint_graph_data": {
        "waypoint_graph": {}
    },
    "travel_time_waypoint_graph_data": {
        "waypoint_graph": {}
    },
    "cost_matrix_data": {
        "data": {},
        "cost_matrix": {}
    },
    "travel_time_matrix_data": {
        "data": {},
        "cost_matrix": {}
    },
    "fleet_data": {
        "vehicle_locations": [
            [
                1
            ]
        ],
        "vehicle_ids": [
            "string"
        ],
        "capacities": [
            [
                1
            ]
        ],
        "vehicle_time_windows": [
            [
                1
            ]
        ],
        "vehicle_break_time_windows": [
            [
                [
                    1
                ]
            ]
        ],
        "vehicle_break_durations": [
            [
                1
            ]
        ],
        "vehicle_break_locations": [
            1
        ],
        "vehicle_types": [
            1
        ],
        "vehicle_order_match": [
            {
                "vehicle_id": 1,
                "order_ids": [
                    1
                ]
            }
        ],
        "skip_first_trips": [
            true
        ],
        "drop_return_trips": [
            true
        ],
        "min_vehicles": 1,
        "vehicle_max_costs": [
            1.0
        ],
        "vehicle_max_times": [
            1.0
        ],
        "vehicle_fixed_costs": [
            1.0
        ]
    },
    "task_data": {
        "task_locations": [
            1
        ],
        "task_ids": [
            "string"
        ],
        "demand": [
            [
                1
            ]
        ],
        "pickup_and_delivery_pairs": [
            [
                1
            ]
        ],
        "task_time_windows": [
            [
                1
            ]
        ],
        "service_times": [
            1
        ],
        "prizes": [
            1.0
        ],
        "order_vehicle_match": [
            {
                "order_id": 1,
                "vehicle_ids": [
                    1
                ]
            }
        ]
    },
    "solver_config": {
        "time_limit": 1.0,
        "objectives": {
            "cost": 1.0,
            "travel_time": 1.0,
            "variance_route_size": 1.0,
            "variance_route_service_time": 1.0,
            "prize": 1.0,
            "vehicle_fixed_cost": 1.0
        },
        "config_file": "string",
        "verbose_mode": true,
        "error_logging": true
    }
}

Status Codes:

• 200 OK –

  Successful Response

  Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "reqId": "string"
  }
  

• 400 Bad Request –

  Value Error Or Validation Error

  Example response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 409 Conflict –

  Failed to get route

  Example response:

  HTTP/1.1 409 Conflict
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 422 Unprocessable Entity –

  Unprocessable Entity or Runtime Error or Out of memory error

  Example response:

  HTTP/1.1 422 Unprocessable Entity
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

• 500 Internal Server Error –

  Any uncaught cuOpt error or Server errors

  Example response:

  HTTP/1.1 500 Internal Server Error
  Content-Type: application/json
  
  {
      "detail": "string"
  }
  

Request Headers:

• CUOPT-DATA-FILE – Name of data file to process in the server’s CUOPT_DATA_DIR when using the local file feature

• CUOPT-RESULT-FILE – Result file name if output dir is enabled and size >= maxresult

• CLIENT-VERSION – cuOpt client version. Set to ‘custom’ to skip version check

• RESULT-TIMEOUT – Optional timeout. If not specified, the call will be synchronous. If specified and a solution is not found before the timeout expires, a request id will be returned which can be polled for a result.