> ## 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.

# SDK quickstart

> Install the Kardinal Python or TypeScript SDK, set your API key, submit the built-in example plan, and read its optimized tours in a few lines of code.

This page takes you from an empty project to an optimized route with the SDK of your choice. It uses the example plan shipped with both SDKs: two vehicles and eight deliveries around central Paris.

## Before you start

You need:

* **An API key.** Sign up on the [Console](https://console.kardinal.ai) and generate a key for your `sandbox` agency — see [Authentication and API keys](https://developers.kardinal.ai/guides/authentication.md). 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](https://developers.kardinal.ai/sdks/installation.md#installing-the-package) explains why.

```bash Python theme={null}
python3 -m venv .venv
source .venv/bin/activate   # on Windows: .venv\Scripts\activate
pip install kardinal-ai
```

```bash TypeScript theme={null}
npm install @kardinal-ai/sdk
```

The Python package installs as `kardinal-ai` and imports as `kardinal`. See [Installation](https://developers.kardinal.ai/sdks/installation.md) for the `kardinal` command-line tool and the module formats.

## Setting your API key

Both SDKs read the key from the `KARDINAL_API_KEY` environment variable:

```bash theme={null}
export KARDINAL_API_KEY="<your sandbox API key>"
```

Keep the key out of your source code. [Client configuration](https://developers.kardinal.ai/sdks/configuration.md) covers the other ways to pass it.

## Submitting the example plan

```python Python theme={null}
from kardinal import Kardinal
from kardinal.routing import examples

k = Kardinal()  # reads KARDINAL_API_KEY
plan = k.routing.plans.submit(examples.small_delivery_plan())
solution = k.routing.solutions.wait(plan.id, timeout=60)  # returns in about 20 seconds
```

```ts TypeScript theme={null}
import { Kardinal, examples } from "@kardinal-ai/sdk";

const k = new Kardinal(); // reads KARDINAL_API_KEY
const plan = await k.routing.plans.submit(examples.smallDeliveryPlan());
const solution = await k.routing.solutions.wait(plan.id, 60_000); // resolves in about 20 seconds
```

`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

```python Python theme={null}
print(solution.final_state)  # optimized, or interrupted/stopped if cut short
for tour in solution.tours or []:  # tours is None when no stop could be planned
    print(tour.resourceId)
    for wp in tour.wayPoints or []:
        if wp.type == "stop":
            print(wp.stopId, wp.arrivalTime, wp.beginTime)
print("Not planned:", solution.unaffectedStopIds or [])
```

```ts TypeScript theme={null}
console.log(solution.finalState); // optimized, or interrupted/stopped if cut short
for (const tour of solution.tours ?? []) {
  // tours is absent when no stop could be planned
  console.log(tour.resourceId);
  for (const wp of tour.wayPoints ?? []) {
    if (wp.type === "stop") {
      console.log(wp.stopId, wp.arrivalTime, wp.beginTime);
    }
  }
}
console.log("Not planned:", solution.unaffectedStopIds ?? []);
```

Each tour is the route of one resource. It lists its waypoints in order: the beginning, then the stops with any breaks between them, then the end. The snippet keeps only the stops.

`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](https://developers.kardinal.ai/api-reference/solution/retrieve-a-plan-solution.md) 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](https://developers.kardinal.ai/sdks/building-plans.md): describe your own fleet and orders, or load a JSON payload you already have.
* [Plan lifecycle](https://developers.kardinal.ai/sdks/plan-lifecycle.md): re-optimize after a change, track a plan without blocking, and list or delete plans.
* [Errors, retries, and warnings](https://developers.kardinal.ai/sdks/errors-and-warnings.md): handle validation errors, limits, and quotas.
* [Moving from sandbox to production](https://developers.kardinal.ai/guides/sandbox-to-production.md): what changes when you switch to a production key.


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