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

# Integration paths

> Read this before you integrate Kardinal into an application: which sections to read, in which order, and the pitfalls at each step.

A path is a reading order for one task. It lists the steps of the task in the order you do them. Each step links the section to read, and nothing more.

## Integrate route optimization into an existing application with an SDK

Use this path when you add Kardinal to an application that already exists. You use the Python SDK or the TypeScript SDK. The steps are in four stages.

### Stage 1: before you write code

1. Read the checklist [Start here if you're an AI agent](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md). Start with the "At a glance" table. Then read [rule 1](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#1-don’t-silently-default-on-an-irreducible-ambiguity-—-ask), [rule 2](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#2-check-capacity-feasibility-before-modeling-orders-and-do-not-resolve-a-shortfall-on-your-own), [rule 3](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#3-treat-contractual-and-hard-constraint-as-two-different-things), [rule 5](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#5-verify-you-have-real-geocoded-positions-before-finalizing), [rule 6](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#6-use-typed-sdk-objects-when-available-otherwise-validate-against-the-data-model-field-by-field), and [rule 9](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#9-size-the-optimization-time-and-test-in-the-sandbox).
2. Use the [Requirements briefing checklist](https://developers.kardinal.ai/guides/requirements-briefing.md). Ask the user every question at once. Include the question about where the sandbox and production keys are. Then wait for the answers before you write the code that builds the plan. In the meantime, you can write the rest, such as reading the key, submitting the plan, and the screens. Don't turn on an option such as `lateDeparture` or `withTraffic`, and don't add `breaks`, unless the data or the user asks for it. If the user can't answer now, leave each unanswered option unset, and make it a setting the operator can fill in. The operator is the company whose tours your app plans. Then list these settings for the user. The working time window (`workingTimeWindow`) is required, so it can't stay unset. Read it from the operator's data, such as each driver's shift, or from a setting the operator fills in. Never write it as a constant in your code. If nobody can answer during your session, give that setting a starting value so the app can plan. Keep it in the settings, not in the code, and list it for the user as your assumption.
3. Find the closest [case study](https://developers.kardinal.ai/case-studies/overview.md), for example [Cold-chain last-mile](https://developers.kardinal.ai/case-studies/cold-chain-last-mile.md). Use it as a starting point. Don't copy it as a model. Its settings, such as `withTraffic`, its working hours and its breaks, belong to that example's client. Keep one in your code only when the user confirms it. The SDK returns it as a typed plan: `examples.cold_chain_plan()` in Python, and `examples.coldChainPlan()` in TypeScript.

### Stage 2: write the plan

4. Follow the [Quickstart](https://developers.kardinal.ai/sdks/quickstart.md). Then read [Loading an existing JSON payload](https://developers.kardinal.ai/sdks/building-plans.md#loading-an-existing-json-payload) and [Validating locally before you spend credits](https://developers.kardinal.ai/sdks/building-plans.md#validating-locally-before-you-spend-credits). In Python, build the plan with `PlanCreate.model_validate_json`. In TypeScript, build it with `parsePlanCreate`. Run [`kardinal init`](https://developers.kardinal.ai/sdks/cli#project-setup-for-ai-coding-assistants) in your project. The `kardinal` command needs an extra install. In Python, install `"kardinal-ai[cli]"`. In TypeScript, also install `commander`. See [Installing the command-line tool](https://developers.kardinal.ai/sdks/installation.md#installing-the-command-line-tool). It writes a skill that tells your coding assistant how to use the SDK.
5. Read these sections only when the question comes up.
   * [Compartments set up before departure](https://developers.kardinal.ai/guides/capacities.md#compartments-set-up-before-departure) explains how to load a vehicle with several goods.
   * [Hard or preferred window](https://developers.kardinal.ai/guides/time-windows.md#hard-or-preferred-window) explains which kind of time window to use.
   * [The default list](https://developers.kardinal.ai/concepts/objectives.md#the-default-list) explains which objectives apply when you write none.
   * [Dates and time zones](https://developers.kardinal.ai/reference/data-model.md#dates-and-time-zones) explains how to write a time.

### Stage 3: follow the optimization from a web backend

6. Check the API key when your application starts. Call `whoami`, then compare the agency it returns with the one in your configuration. A sandbox key and a production key look alike. Read [Checking the key at startup](https://developers.kardinal.ai/sdks/configuration.md#checking-the-key-at-startup).
7. Read [Waiting in a web backend or serverless function](https://developers.kardinal.ai/sdks/plan-lifecycle.md#waiting-in-a-web-backend-or-serverless-function). Submit the plan, then store its id. Read the state later. Never call `wait` inside an HTTP request.
8. Keep the warnings that `submit`, `update`, and `replace` return, for example next to the plan id. A later `get` doesn't return them. Show them in your application to the person who submitted the plan, for example the planner. The API returns a warning when it changes part of your plan, for example when you ask for a longer `maxOptimizationDuration` than your limit allows. The sandbox also returns warnings that production doesn't, for example when it forces straight-line (crow-fly) distances. These warnings aren't errors. Build the message for the planner from `properties.path` and the value stored at that path, not from `message` or `details`. The SDKs also write each kind of warning in your logs. Read [Warnings on successful calls](https://developers.kardinal.ai/sdks/errors-and-warnings.md#warnings-on-successful-calls).
9. Keep the id of the plan you submit for each day. When the planner runs that day again, for example with other settings, call `replace` on that id. Don't call `submit` again. A new plan bills every stop again. The same plan, with the same stops, isn't billed again within 24 hours of its creation. Read [Replacing a plan from your own data](https://developers.kardinal.ai/sdks/plan-lifecycle.md#replacing-a-plan-from-your-own-data) and [How credits work](https://developers.kardinal.ai/reference/pricing-and-credits.md#how-credits-work).

### Stage 4: test, then go to production

10. Read [Differences between sandbox and production](https://developers.kardinal.ai/guides/sandbox-to-production.md#differences-between-sandbox-and-production). The sandbox limits the optimization time. Wait about one minute at most, as [rule 9](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md#9-size-the-optimization-time-and-test-in-the-sandbox) says.
11. Read [Sizing `maxOptimizationDuration` for a large problem](https://developers.kardinal.ai/guides/handling-large-volumes#sizing-maxoptimizationduration-for-a-large-problem) before you run a large plan.
12. Read [How credits work](https://developers.kardinal.ai/reference/pricing-and-credits.md#how-credits-work). Tell the user before you run a plan in production.

When you read a solution, use [Reading the result](https://developers.kardinal.ai/sdks/quickstart.md#reading-the-result). It shows how to list the stops of each tour, with their times. It also shows how to find the stops that the engine could not plan.


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