Before you start
You need:- An API key. Sign up on the Console and generate a key for your
sandboxagency — see Authentication and API keys. A sandbox key consumes no credits, which makes it the right key for this page. - A runtime. Python 3.10 or later, or Node.js 22 or later.
Installing the package
Install the Python package in a virtual environment, which is a private folder of packages for one project. Installation explains why.kardinal-ai and imports as kardinal. See Installation for the kardinal command-line tool and the module formats.
Setting your API key
Both SDKs read the key from theKARDINAL_API_KEY environment variable:
Submitting the example plan
submit sends the plan, which starts its optimization, and returns it with the id the server assigned. wait follows the optimization and returns the solution once it’s over.
The example plan asks for a 10-second optimization. The sandbox caps optimizations at 5 seconds, so submit returns a warning saying the duration was clamped: that’s expected, and plan.warnings lists it.
Reading the result
arrivalTime is when the vehicle gets to a stop. beginTime is when the service starts. When the vehicle arrives before the stop’s time window opens, it waits, so beginTime is later than arrivalTime. Show beginTime to your customer.
A stop the engine could not plan is in no tour. It is listed in unaffectedStopIds, and no error reports it.
The final state says how the optimization ended: check it before treating the result as final. See Retrieve a plan solution in the API Reference for every field of the solution.
Why wait rather than get
The API is asynchronous. Right after submit, the plan is still waiting or being processed: solutions.get then fails with a 404, and a moment later returns whatever the engine has found so far, which can be empty or incomplete. wait returns only once the optimization is over.
Next steps
- Building plans with typed models: describe your own fleet and orders, or load a JSON payload you already have.
- Plan lifecycle: re-optimize after a change, track a plan without blocking, and list or delete plans.
- Errors, retries, and warnings: handle validation errors, limits, and quotas.
- Moving from sandbox to production: what changes when you switch to a production key.

