# Kardinal Route Optimization API

> Documentation for Kardinal's self-service logistics optimization API.

- [First API call](https://developers.kardinal.ai/getting-started/first-api-call.md): Get a sandbox key and calculate your first route in under 15 minutes.
- [Complete route walkthrough](https://developers.kardinal.ai/getting-started/complete-tour-walkthrough.md): Model a representative case: multiple vehicles, depots, and time windows, through to a usable result.
- [Start here if you're an AI agent](https://developers.kardinal.ai/getting-started/agent-modeling-checklist.md): Mandatory checklist for any AI agent modeling a client's logistics problem as a Kardinal plan — read this before writing any integration code.
- [How the optimization engine works](https://developers.kardinal.ai/concepts/how-the-optimization-engine-works.md): What is minimized/maximized, and the trade-off between solution quality and computation time.
- [Objectives and how they're ranked](https://developers.kardinal.ai/concepts/objectives.md): How the engine compares solutions one objective at a time, what each built-in objective measures, and how to choose an order.
- [Hard vs soft constraints](https://developers.kardinal.ai/concepts/hard-vs-soft-constraints.md): Feasibility logic and why a problem can be declared infeasible.
- [Data security and handling](https://developers.kardinal.ai/concepts/data-security.md): Hosting and compliance for delivery and end-customer data.
- [Vocabulary mapping](https://developers.kardinal.ai/guides/vocabulary-mapping.md): Generic vehicle-routing vocabulary mapped to Kardinal's own terms.
- [Requirements briefing checklist](https://developers.kardinal.ai/guides/requirements-briefing.md): The questions to ask about an operation before you model it as a Kardinal plan — business facts a raw data export can't tell you.
- [Authentication and API keys](https://developers.kardinal.ai/guides/authentication.md): Key generation, rotation, and storage best practices.
- [Moving from sandbox to production](https://developers.kardinal.ai/guides/sandbox-to-production.md): Environment differences and a production launch checklist.
- [Handling large volumes](https://developers.kardinal.ai/guides/handling-large-volumes.md): Batch import, pagination, and async mode for long-running calculations.
- [Modeling advanced constraints](https://developers.kardinal.ai/guides/advanced-constraints.md): Heterogeneous capacities, driver skills, mandatory breaks, multiple time windows.
- [Cost modeling](https://developers.kardinal.ai/guides/cost-modeling.md): Represent cost in real currency with `cost`, piecewise-linear cost functions, and custom objectives via `customCost`.
- [Multi-trip tours (depot returns)](https://developers.kardinal.ai/guides/multi-trip-tours.md): Model a vehicle that reloads at the depot and runs several rounds within one shift.
- [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: skip trucks, tanker swaps, container exchange.
- [Handling infeasibility](https://developers.kardinal.ai/guides/handling-infeasibility.md): Interpret a no-solution response and diagnose the constraint at fault.
- [Real-time re-optimization](https://developers.kardinal.ai/guides/real-time-reoptimization.md): Trigger a recalculation following a disruption (delay, cancellation, urgent order).
- [Manual assignment and supervision](https://developers.kardinal.ai/guides/manual-assignment-and-supervision.md): Lock a sequence with `state`, supervise a tour live, and pin a stop to one resource.
- [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): Retrieving a collection of plans 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 absent, the first page is returned, with the default number of items.
- [Create a plan](https://developers.kardinal.ai/api-reference/plan/create-a-plan.md): 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 most recent entry in the plan's state history: 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 `PlanSt…
- [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): Index of the Resource, Order/Stop, Capacities, Time window, Breaks, and Constraints objects, with a link to each one's full field reference.
- [Glossary](https://developers.kardinal.ai/reference/glossary.md): Unified terminology used throughout the Kardinal documentation.
- [Limits and quotas](https://developers.kardinal.ai/reference/limits-and-quotas.md): Rate limits, maximum payload size, computation time, and SLA.
- [Pricing and credits](https://developers.kardinal.ai/reference/pricing-and-credits.md): How credit-based billing works: free credits, consumption, and packs.
- [Changelog](https://developers.kardinal.ai/reference/changelog.md): API version history.
- [Modeling examples by industry](https://developers.kardinal.ai/case-studies/overview.md): Combined, realistic examples of Kardinal modeling the constraints that make each logistics vertical distinctive.
- [Parcel & express](https://developers.kardinal.ai/case-studies/parcel-express.md): Pickup/drop-off point rounds gated by capacity, zone preference, a mixed last-mile fleet, and predictive traffic on one urban network.
- [Waste collection](https://developers.kardinal.ai/case-studies/waste-collection.md): Alternative disposal outlets, material changeover time, incompatible loads, and heavy-vehicle routing on one municipal round.
- [Cold-chain last-mile](https://developers.kardinal.ai/case-studies/cold-chain-last-mile.md): 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): Skill preference on demanding jobs, opportunistic scheduling, a travel-distance cap, and technicians dispatched 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): Reserved warehouse slots, load-aware CO2 accounting, self-closing consolidation loops, and a real overnight rest on one long-haul lane.
- [Retail last-mile](https://developers.kardinal.ai/case-studies/retail-last-mile.md): Key-holder-only access windows, blended subcontractor/in-house costs, pre-opening store drops, and trusted-keychain deliveries on one retail network.

## OpenAPI Specs

- [openapi](/openapi.yaml)


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