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

# Data model

> Index of the Resource, Order/Stop, Capacities, Time window, Breaks, and Constraints objects, with a link to each one's full field reference.

This page is a map, not a field reference: each section below is a short orientation to one part of the plan, linking straight to the schema panel of the [API reference](/api-reference/plan/create-a-plan) that actually documents every field, type, and constraint — that's where to look up a specific field's full definition. A plan is built from two lists — `resources` (vehicles/drivers) and `orders` (what needs to be done) — plus plan-level fields that add constraints spanning several of them. See [First API call](/getting-started/first-api-call) for the request/response shapes and [How the optimization engine works](/concepts/how-the-optimization-engine-works) for what the engine does with these fields.

## Resource (vehicle-driver pair)

One vehicle-driver pair for the duration of the plan — id, working hours, capacities, skills, breaks, and travel constraints. See the [`resources` schema](/api-reference/plan/create-a-plan#body-resources).

### Vehicle profiles

Mode of transport and its travel constraints (`fly`, `pedestrian`, `bicycle`, `scooter`, `motorbike`, `car`, `truck`), nested under each resource's `vehicleProfile`. The `fly` profile additionally takes a `kmph` field — a constant travel speed used to compute crow-fly travel times, since it has no road network to derive one from. On a `truck` profile, `height`, `width`, and `length` are in metres and `grossWeight` in kilograms. See the [`resources` schema](/api-reference/plan/create-a-plan#body-resources).

## Order, stop

An order is one or more stops that must all be planned onto the same resource, in array order. See the [`orders` schema](/api-reference/plan/create-a-plan#body-orders).

A stop's `kind` (`pickup`, `delivery`, or `acknowledgement`) sets which way its `capacities` move, from the resource's point of view: a `pickup` loads its quantity at the stop, and a `delivery` unloads it there. A negative quantity reverses that direction: a `delivery` of `-100` has the same effect as a `pickup` of `100`.

Within one order, a `pickup` and a `delivery` carry the same goods: the resource loads them at the first stop and unloads them at the second. A `delivery` whose order has no `pickup` is assumed loaded at departure, which shows in the tour's `filledCapacitiesAtBegin`. Pickups and deliveries from different orders are distinct goods, even when their quantities match.

## Capacities

Free-form map tracking what a resource carries and what a stop consumes or releases, declared on both resources and stops. See the [`resources`](/api-reference/plan/create-a-plan#body-resources) and [`orders`](/api-reference/plan/create-a-plan#body-orders) schemas.

A solution reports `filledCapacitiesAtBegin`/`filledCapacitiesAtEnd`/`filledCapacitiesAfterStop` (capacities loaded at the start, end, and after each stop) and `maxFilledCapacities` (the peak reached during the tour) — see the `Tour` and `WayPointStop` schemas in the [API reference](/api-reference/solution/retrieve-a-plan-solution). A capacity declared on a resource with a ceiling no tour can reach reads back as a read-only KPI (for example `nbPackages`) without affecting the optimization.

### Shared capacity pools

Plan-level `sharedCapacities` flag pooling a capacity key across all of a resource's stops, regardless of order. See the [`sharedCapacities` schema](/api-reference/plan/create-a-plan#body-shared-capacities).

## Time windows

`TimeWindow` (plain `{begin, end}`) and `TaggedTimeWindow` (the same shape plus optional `resourceTags`), used for working hours, breaks, and a stop's authorized/preferred windows. See the [`resources`](/api-reference/plan/create-a-plan#body-resources) and [`orders`](/api-reference/plan/create-a-plan#body-orders) schemas.

## Breaks

A resource's `breaks` array, mixing `timeWindowBreak`, `workingDurationSlidingBreak`, and `travelDurationSlidingBreak` entries. See the [`resources` schema](/api-reference/plan/create-a-plan#body-resources).

## Constraints catalog

`additionalConstraints` (scoped to specific tags) and `globalConstraints` (scoped to the whole fleet) beyond what resources/orders/stops express directly. See the [`additionalConstraints`](/api-reference/plan/create-a-plan#body-additional-constraints) and [`globalConstraints`](/api-reference/plan/create-a-plan#body-global-constraints) schemas.

## Plan-level fields

Fields that configure the plan as a whole: `agencyId`, `tz`, `lateDeparture`, `maxOptimizationDuration`, `sharedCapacities`, `objectives`, `additionalConstraints`, `globalConstraints`, `accessDurationsByStopTag`, `overlappingCapacitiesByStopTag`, `setupDurations`, `additionalOperationDurations`. See the [`Plan` schema](/api-reference/plan/create-a-plan).

## Status and state

Two read-only fields track a plan's lifecycle: `status` (a detailed breakdown per stage — waiting room, creation, optimization, and traffic fetching) and `state` (a single summary value, `optimized` once no better solution can be found). See [How the optimization engine works](/concepts/how-the-optimization-engine-works#the-quality-vs-computation-time-trade-off) for the full polling pattern, and `GET /plans/{planId}/state` to retrieve `state` directly.

## Positions and geocoding

Every position in a plan (each stop's `position`, and a resource's `departure`/`arrival`) is a `{lat, lon}` pair in decimal degrees. The API does not geocode addresses: geocode them on your side before building the plan, with whichever geocoding provider your integration already uses. If you can't geocode your addresses yourself, contact [customer.success@kardinal.ai](mailto:customer.success@kardinal.ai): the team can geocode an address set for you on request.

A wrongly geocoded position raises no error: it silently routes to the wrong place. Spot-check a sample of geocoded stops on a map before submitting. If an address can't be geocoded precisely, treat it as a data-quality gap rather than falling back to an approximation such as a town or postal-code centroid, since stops sharing that point collapse onto it. See [§5 of the AI agent checklist](/getting-started/agent-modeling-checklist#5-verify-you-have-real-geocoded-positions-before-finalizing), and [Geocoding and addresses](/guides/requirements-briefing#8-geocoding-and-addresses) for the questions to settle with the operations team.

## Depot vs. position

Depots are not first-class objects in this API — there is no `Depot` schema. A resource's `departure`/`arrival` positions (a raw `{lat, lon}`, or `"atFirstPosition"` for `arrival`) are how a depot is represented: resolve it to its position on the client side before building the plan. A "depot" tag such as `"depot:main"` (see [Multi-trip tours](/guides/multi-trip-tours#the-core-mechanic-pair-each-delivery-with-its-own-depot-pickup)) is an arbitrary stop tag your integration defines, not a reference to any API object. See the [`resources` schema](/api-reference/plan/create-a-plan#body-resources).

## See also

* [Hard vs soft constraints](/concepts/hard-vs-soft-constraints) — which of the preceding bend under pressure and which don't.
* [Modeling advanced constraints](/guides/advanced-constraints) — worked examples for capacities, skills, breaks, time windows, and optional steps that gate a mandatory stop.
* [How the optimization engine works](/concepts/how-the-optimization-engine-works) — objectives and the optimization loop that consumes this data.


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