> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you're integrating Kardinal into an application with an SDK, start with Integration paths: https://developers.kardinal.ai/getting-started/integration-paths.md. It lists the sections to read, in order. If you follow Integration paths, you don't need llms-full.txt or openapi.yaml. Each step links the section you need.

# Kardinal SDKs

> What the Kardinal Python and TypeScript SDKs do, how they map to the REST API, and when to use an SDK, the command-line tool, or plain HTTP calls instead.

Kardinal publishes two official SDKs for the Route Optimization API: the **Kardinal Python SDK** (`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.

> [card] [Quickstart](https://developers.kardinal.ai/sdks/quickstart.md)
>
> Install an SDK and get your first optimized route in a few minutes.

> [card] [Plan lifecycle](https://developers.kardinal.ai/sdks/plan-lifecycle.md)
>
> 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](https://developers.kardinal.ai/api-reference/plan/create-a-plan.md) 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 `operationDurationn` produces a valid but wrong plan.
* **Waiting for a solution.** `wait` polls 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 a `5xx`. Creating a plan never is, so a retry can't create it twice.

## Choosing an SDK, the command-line tool, or the REST API

| You want to… | Use |
| - | - |
| Integrate Kardinal into a Python or Node.js app | The matching SDK |
| Integrate from another language | The [REST API](https://developers.kardinal.ai/api-reference/plan/create-a-plan.md) directly, starting with [First API call](https://developers.kardinal.ai/getting-started/first-api-call.md) |
| Check a key, validate a plan file, or script a call from a shell or a CI job | The [`kardinal` command-line tool](https://developers.kardinal.ai/sdks/cli), shipped with both SDKs |
| Call the API from a web page | Not supported: keep the key on a server, see [Keeping the key server-side](https://developers.kardinal.ai/sdks/configuration.md#keeping-the-key-server-side) |

## What the SDKs cover

Every endpoint of the API has an SDK method in both languages, and a command in the `kardinal` command-line tool.

| Operation | Endpoint | Python | TypeScript | Command |
| - | - | - | - | - |
| Create a plan and start its optimization | [`POST /plans`](https://developers.kardinal.ai/api-reference/plan/create-a-plan) | `plans.submit` | `plans.submit` | `routing plans submit` |
| Retrieve a plan | [`GET /plans/{planId}`](https://developers.kardinal.ai/api-reference/plan/retrieve-a-plan) | `plans.get` | `plans.get` | `routing plans get` |
| Replace a plan and re-optimize it | [`PUT /plans/{planId}`](https://developers.kardinal.ai/api-reference/plan/update-a-plan) | `plans.update` | `plans.update` | `routing plans update` |
| Delete a plan | [`DELETE /plans/{planId}`](https://developers.kardinal.ai/api-reference/plan/delete-a-plan) | `plans.delete` | `plans.delete` | `routing plans delete` |
| List plans, one page or all of them | [`GET /plans`](https://developers.kardinal.ai/api-reference/plan/retrieve-the-list-of-plans-in-a-light-representation) | `plans.list`, `plans.iter_all` | `plans.list`, `plans.iterAll` | `routing plans list` |
| Restart or stop an optimization | [`PUT /plans/{planId}/running`](https://developers.kardinal.ai/api-reference/plan/stop-or-restart-the-optimization-of-a-plan) | `plans.start`, `plans.stop` | `plans.start`, `plans.stop` | `routing plans start`, `routing plans stop` |
| Read the plan's state | [`GET /plans/{planId}/state`](https://developers.kardinal.ai/api-reference/plan/retrieve-the-latest-state-of-a-plan) | `plans.get_status` | `plans.getStatus` | `routing plans status` |
| Wait for the optimization to end, then read the solution | `GET /plans/{planId}/state`, then `/solution` | `solutions.wait` | `solutions.wait` | `routing solutions wait` |
| Read the current best solution | [`GET /plans/{planId}/solution`](https://developers.kardinal.ai/api-reference/solution/retrieve-a-plan-solution) | `solutions.get` | `solutions.get` | `routing solutions get` |
| Read the objective values only | [`GET /plans/{planId}/solution/objectives`](https://developers.kardinal.ai/api-reference/solution/retrieve-the-objectives-of-a-plan-solution) | `solutions.get_objectives` | `solutions.getObjectives` | `routing solutions objectives` |

All methods hang off the client, under `k.routing`. The [Python SDK reference](https://developers.kardinal.ai/sdks/python/reference.md) and the [TypeScript SDK reference](https://developers.kardinal.ai/sdks/typescript/reference.md) give each method's parameters, return value, and errors. Each reference summarizes the fields of a solution in its "Solution fields" section. Every other field is documented in the [API Reference](https://developers.kardinal.ai/api-reference/plan/create-a-plan.md): 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](https://developers.kardinal.ai/guides/authentication.md).
* **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](https://developers.kardinal.ai/sdks/plan-lifecycle.md#waiting-in-a-web-backend-or-serverless-function) for how to use it from a server.

## Versions and compatibility

| SDK | Package | Current version | Runtime | API version |
| - | - | - | - | - |
| Python | [`kardinal-ai`](https://pypi.org/project/kardinal-ai/) | 2.2.1 | Python 3.10 or later | 1.0.2 |
| TypeScript | [`@kardinal-ai/sdk`](https://www.npmjs.com/package/@kardinal-ai/sdk) | 1.3.0 | Node.js 22 or later | 1.0.2 |

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](https://developers.kardinal.ai/sdks/python/changelog.md) and the [TypeScript SDK changelog](https://developers.kardinal.ai/sdks/typescript/changelog.md), and the [API changelog](https://developers.kardinal.ai/reference/changelog.md) for the API itself.

Version 1.1.0 of both SDKs is an exception to semantic versioning, because it changes behaviour in ways that can break existing code. Read the [Python SDK changelog](https://developers.kardinal.ai/sdks/python/changelog.md) and the [TypeScript SDK changelog](https://developers.kardinal.ai/sdks/typescript/changelog.md) before you upgrade, because they list what changed.

## Source code, license, and support

Both SDKs are open source under the MIT license:

* [github.com/KardinalAI/kardinal-sdk-python](https://github.com/KardinalAI/kardinal-sdk-python)
* [github.com/KardinalAI/kardinal-sdk-typescript](https://github.com/KardinalAI/kardinal-sdk-typescript)

To report a bug or ask for a change, open an issue on the repository of the SDK concerned. For a question about your account, your quotas, or the API's behavior, contact [customer.success@kardinal.ai](mailto:customer.success@kardinal.ai).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.