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 ({'boolean', 'null'}) – 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" }
Value Error Or Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "detail": "string" }
Failed to get route
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "detail": "string" }
Unprocessable Entity or Runtime Error or Out of memory error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": "string" }
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 {}
Value Error Or Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "detail": "string" }
Failed to get route
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "detail": "string" }
Unprocessable Entity or Runtime Error or Out of memory error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": "string" }
Any uncaught cuOpt error or Server errors
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "detail": "string" }
- 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 ({'boolean', 'null'}) – 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" }
Value Error Or Validation Error
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "detail": "string" }
Failed to get route
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "detail": "string" }
Unprocessable Entity or Runtime Error or Out of memory error
Example response:
HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { "detail": "string" }
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.