kardinal-ai on PyPI) and the Kardinal TypeScript SDK (@kardinal-ai/sdk on npm, which also works from JavaScript). Both cover the same operations with the same behavior: submit a plan, follow its optimization, retrieve the solution, and update the plan to re-optimize it.
Quickstart
Install an SDK and get your first optimized route in a few minutes.
Plan lifecycle
Submit, wait, re-optimize, stop, list, and delete plans.
What the SDKs do
An SDK doesn’t change what the API does. It removes the code you would otherwise write around it:- Typed plan objects. Plans, resources, orders, and stops are typed from the same OpenAPI specification the API Reference is built from, so your editor completes field names and flags wrong types.
- Local checks before sending. A misspelled field name is refused before the request leaves your machine. The API itself silently drops a key it doesn’t know, so without this check a typo such as
operationDurationnproduces a valid but wrong plan. - Waiting for a solution.
waitpolls the plan’s state at a reasonable pace and returns the solution once the optimization is over, instead of a loop you write and tune yourself. - Errors you can branch on. Each API error becomes a typed exception, with every error of the response attached, and a flag that says whether retrying is safe.
- Retries where they’re safe. Reads and updates are retried after a network error, a
429, or a5xx. Creating a plan never is, so a retry can’t create it twice.
Choosing an SDK, the command-line tool, or the REST API
What the SDKs cover
Every endpoint of the API has an SDK method in both languages, and a command in thekardinal command-line tool.
All methods hang off the client, under
k.routing. The Python SDK reference and the TypeScript SDK reference give each method’s parameters, return value, and errors. Field-level documentation stays in the API Reference: the SDKs reuse its models without redefining them.
What’s not covered
- Account and key management. Generating, rotating, and revoking an API key are Console-only operations, with no endpoint behind them — see Authentication and API keys.
- Browsers. The TypeScript SDK targets Node.js only, and an API key must never reach a browser.
- An asynchronous Python client. The Python SDK is synchronous: see Waiting in a web backend or serverless function for how to use it from a server.
Versions and compatibility
Each SDK follows semantic versioning on its own: a Python release and a TypeScript release don’t share version numbers. See the Python SDK changelog and the TypeScript SDK changelog, and the API changelog for the API itself.