# Kardinal Route Optimization API

> Documentation for Kardinal's self-service logistics optimization API. Create an account and get an API key at https://console.kardinal.ai.

- [Introduction](https://developers.kardinal.ai/index.md): Start here to integrate Kardinal's Route Optimization API: tutorials, modeling guides, engine concepts, industry examples, and the full API reference.
- [First API call](https://developers.kardinal.ai/getting-started/first-api-call.md): Get your API token, submit a minimal plan with one vehicle and three orders, then retrieve the optimized route the engine computes for it, in under 15 minutes.
- [Complete route walkthrough](https://developers.kardinal.ai/getting-started/complete-tour-walkthrough.md): Build a realistic plan step by step, with two vans, two depots, and delivery time windows, then read the result and avoid the common pitfalls at this stage.
- [Start here if you're an AI agent](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md): Mandatory checklist for any AI agent that models a client's logistics problem as a Kardinal plan: the rules to follow before you write any integration code.
- [How the optimization engine works](https://developers.kardinal.ai/concepts/how-the-optimization-engine-works.md): How the engine trades solution quality for computation time, how to poll a plan's state until its solution is ready, what an update does, and what you control.
- [Objectives and how they're ranked](https://developers.kardinal.ai/concepts/objectives.md): How the engine ranks solutions one objective at a time, what each built-in objective measures, the default order, and how to choose an order for your operation.
- [Hard vs soft constraints](https://developers.kardinal.ai/concepts/hard-vs-soft-constraints.md): Which plan fields the engine must respect and which it respects only if it can, how it settles conflicts, and why a stop can end up unplanned without an error.
- [Data security and handling](https://developers.kardinal.ai/concepts/data-security.md): What data flows through the API, where it's hosted, how Kardinal isolates, encrypts, and retains it, its role under GDPR, and its current certification status.
- [Vocabulary mapping](https://developers.kardinal.ai/guides/vocabulary-mapping.md): Translate the generic vehicle-routing terms you know from other tools, such as VRP, depot, time windows, or pickup and delivery, into Kardinal's own vocabulary.
- [Requirements briefing checklist](https://developers.kardinal.ai/guides/requirements-briefing.md): Questions to ask about an operation before modeling it as a Kardinal plan: business facts, like hard time windows or depot reloads, a data export can't show.
- [Authentication and API keys](https://developers.kardinal.ai/guides/authentication.md): Generate your long-term API token in the Console, send it as a bearer token, and store, rotate, and troubleshoot it safely across sandbox and production.
- [Moving from sandbox to production](https://developers.kardinal.ai/guides/sandbox-to-production.md): How sandbox and production differ for the same builder account, a checklist to run before switching, and how to manage a separate API token per environment.
- [Handling large volumes](https://developers.kardinal.ai/guides/handling-large-volumes.md): Submit a large plan in a single request, page through long result lists, and size maxOptimizationDuration so the engine has enough time for a bigger problem.
- [Modeling advanced constraints](https://developers.kardinal.ai/guides/advanced-constraints.md): Model a fleet that isn't uniform: varied vehicle capacities, driver skills, mandatory breaks, multiple time windows per stop, and optional steps gating a stop.
- [Cost modeling](https://developers.kardinal.ai/guides/cost-modeling.md): Express cost in real currency with the cost object, use piecewise-linear cost functions, guarantee a minimum revenue per tour, cap a cost across the whole fleet, and build custom objectives.
- [Multi-trip tours (depot returns)](https://developers.kardinal.ai/guides/multi-trip-tours.md): Model vehicles that reload at the depot and run several rounds in one shift, count depot time once per visit, and limit simultaneous depot visits and returns.
- [Swap-body and container-exchange orders](https://developers.kardinal.ai/guides/swap-body-exchange.md): Model fleets that carry one exchangeable unit at a time and swap it at each site, like skip trucks, tanker swaps, or container exchange, without double-booking.
- [Handling infeasibility](https://developers.kardinal.ai/guides/handling-infeasibility.md): Spot when a solution leaves stops unplanned or a tour invalid, find which hard constraint is at fault, and pick a strategy to make the plan feasible again.
- [Real-time re-optimization](https://developers.kardinal.ai/guides/real-time-reoptimization.md): Update a running plan after a delay, cancellation, or urgent order, so the engine repairs its solution instead of starting over, and choose how often to update.
- [Manual assignment and supervision](https://developers.kardinal.ai/guides/manual-assignment-and-supervision.md): Lock part of a tour while the engine re-plans the rest, supervise a tour live as it progresses, and reserve a stop for one resource without making it mandatory.
- [Kardinal SDKs](https://developers.kardinal.ai/sdks/overview.md): 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.
- [SDK quickstart](https://developers.kardinal.ai/sdks/quickstart.md): 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.
- [Installation](https://developers.kardinal.ai/sdks/installation.md): Install the Kardinal Python or TypeScript SDK and its optional kardinal command-line tool, check the supported runtimes, and verify that the setup works.
- [Client configuration](https://developers.kardinal.ai/sdks/configuration.md): Create a Kardinal SDK client, pass your API key safely, switch between sandbox and production, and tune request timeouts and retries in Python or TypeScript.
- [Building plans with typed models](https://developers.kardinal.ai/sdks/building-plans.md): Describe your fleet and orders with the SDKs' typed models, load a JSON payload you already have, and validate a plan locally before you spend any credits.
- [Plan lifecycle](https://developers.kardinal.ai/sdks/plan-lifecycle.md): Submit a plan, wait for or track its optimization, re-optimize it after a change, stop or restart it, then list and delete plans with the Kardinal SDKs.
- [Errors, retries, and warnings](https://developers.kardinal.ai/sdks/errors-and-warnings.md): How the Kardinal SDKs turn API errors into typed exceptions, which calls they retry and when, and how to read the warnings returned on a successful call.
- [Command-line tool](https://developers.kardinal.ai/sdks/cli.md): Use the kardinal command shipped with both SDKs to check your API key, validate plan files for free, script calls in CI, and set up projects for AI assistants.
- [Python SDK reference](https://developers.kardinal.ai/sdks/python/reference.md): Every public class, method, and exception of the Kardinal Python SDK (kardinal-ai): signatures, the API endpoint behind each call, return values, and errors.
- [TypeScript SDK reference](https://developers.kardinal.ai/sdks/typescript/reference.md): Every public class, method, and error of the Kardinal TypeScript SDK (@kardinal-ai/sdk): signatures, the API endpoint behind each call, and what each returns.
- [Python SDK changelog](https://developers.kardinal.ai/sdks/python/changelog.md): Version history of the Kardinal Python SDK (kardinal-ai on PyPI): what each release adds or changes, and which version of the Route Optimization API it targets.
- [TypeScript SDK changelog](https://developers.kardinal.ai/sdks/typescript/changelog.md): Version history of the Kardinal TypeScript SDK (@kardinal-ai/sdk on npm): what each release adds or changes, and the Route Optimization API version it targets.
- [Retrieve the list of plans, in a light representation](https://developers.kardinal.ai/api-reference/plan/retrieve-the-list-of-plans-in-a-light-representation.md): Lists your agency's plans in a light representation: `status`, `state`, and resource and order counts, without resources, orders, or constraints. The list is always paginated: - if `page` is absent, its default value is used, - if `itemsPerPage` is absent, its default value is used, - so if both are…
- [Create a plan](https://developers.kardinal.ai/api-reference/plan/create-a-plan.md): Creates a plan from your resources, orders, and constraints, and starts optimizing it. The plan id is generated by the service: an `id` sent in the payload is ignored and replaced by a generated one. Use the id returned in the response to address the plan on the other endpoints.
- [Retrieve a plan](https://developers.kardinal.ai/api-reference/plan/retrieve-a-plan.md): Returns the plan currently stored for this `id`, reflecting any updates applied since it was created.
- [Update a plan](https://developers.kardinal.ai/api-reference/plan/update-a-plan.md): Replaces the plan's data for this `id`, keeping the same `id`. The `version` is incremented, and the plan re-optimized, only if its content changed: a body identical to the stored plan changes nothing, keeps the same `version`, and isn't billed. The engine treats a changed plan as an update to the s…
- [Delete a plan](https://developers.kardinal.ai/api-reference/plan/delete-a-plan.md): Permanently deletes the plan and its solution; any optimization in progress is stopped.
- [Stop or restart the optimization of a plan](https://developers.kardinal.ai/api-reference/plan/stop-or-restart-the-optimization-of-a-plan.md): Stops or restarts optimization on the current version of the plan, without changing its data or `version`.
- [Retrieve the latest state of a plan](https://developers.kardinal.ai/api-reference/plan/retrieve-the-latest-state-of-a-plan.md): Returns the latest state of a plan, as a single summary value (`waiting`, `processing`, `preOptimizing`, and so on — see `PlanState`). For the detailed per-stage breakdown (waiting room, creation, optimization, and, if predictive traffic is enabled, traffic fetching), see `PlanStatus` on the plan it…
- [Retrieve a plan solution](https://developers.kardinal.ai/api-reference/solution/retrieve-a-plan-solution.md): Returns the current best solution for the plan. It may still improve while optimization continues — check the plan's state (`GET /plans/{planId}/state`) to know whether it has settled.
- [Retrieve the objectives of a plan solution](https://developers.kardinal.ai/api-reference/solution/retrieve-the-objectives-of-a-plan-solution.md): Returns the achieved value of each objective in the plan's `objectives` list for the current solution, without the full list of tours.
- [Data model](https://developers.kardinal.ai/reference/data-model.md): Map of the objects in a plan, such as Resource, Order, Stop, Capacities, Time windows, Breaks, and Constraints, with a link to each one's full field reference.
- [Glossary](https://developers.kardinal.ai/reference/glossary.md): Definitions of the Kardinal-specific terms used across the docs, such as agency, resource, order, and unique stop, with links to the pages that cover them.
- [Limits and quotas](https://developers.kardinal.ai/reference/limits-and-quotas.md): Current rate limits, computation time, and payload size in sandbox and production, support response times, and what to do on a 403 limit error or 429 overload.
- [Pricing and credits](https://developers.kardinal.ai/reference/pricing-and-credits.md): How credit billing works: 1,000 free credits, one credit per unique stop optimized, free sandbox runs, buying credit packs, and what happens when you run out.
- [Changelog](https://developers.kardinal.ai/reference/changelog.md): Version history of Kardinal's Route Optimization API: what changed in each release, including new behavior, changed responses, and fields you need to update.
- [Modeling examples by industry](https://developers.kardinal.ai/case-studies/overview.md): One realistic example per logistics industry, combining the constraints that make it distinctive, so you can check quickly whether Kardinal fits your operation.
- [Parcel & express](https://developers.kardinal.ai/case-studies/parcel-express.md): Parcel and express example: pickup/drop-off point rounds gated by capacity, zone preference, a mixed last-mile fleet, and predictive traffic in one city.
- [Waste collection](https://developers.kardinal.ai/case-studies/waste-collection.md): Waste collection example: alternative disposal outlets, material changeover time, incompatible loads, and heavy-vehicle routing for a mixed fleet of trucks.
- [Cold-chain last-mile](https://developers.kardinal.ai/case-studies/cold-chain-last-mile.md): Cold-chain example: a reconfigurable refrigerated compartment, trusted-keychain deliveries, zone preference, and predictive traffic on one refrigerated network.
- [Field services](https://developers.kardinal.ai/case-studies/field-services.md): Field-service example: skill preference on demanding jobs, opportunistic scheduling of backlog jobs, a travel-distance cap, and technicians who start from home.
- [Bulky & heavy goods](https://developers.kardinal.ai/case-studies/bulky-heavy-goods.md): Capacity-gated customer returns, a subcontractor revenue floor, equipment-dependent service time, and two-person crews on one delivery-and-install fleet.
- [Heavy long distance](https://developers.kardinal.ai/case-studies/heavy-long-distance.md): Heavy long-distance example: reserved warehouse slots, load-aware CO2 accounting, self-closing consolidation loops, and a real overnight rest between loading and delivery.
- [Retail last-mile](https://developers.kardinal.ai/case-studies/retail-last-mile.md): Retail example: key-holder-only access windows, blended subcontractor and in-house costs, pre-opening store drops, and trusted-keychain deliveries in one plan.

## OpenAPI Specs

- [openapi](/openapi.yaml)


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