kardinal-ai 2.2.1. Install it with pip install kardinal-ai, import it as kardinal. Every method below is synchronous. The fields of a solution are in Solution fields. The fields of a plan are in the API Reference.
Client
Kardinal
The methods hang off
k.routing.plans and k.routing.solutions. The client holds an httpx connection pool: use it as a context manager (with Kardinal() as k:) or call k.close(). See Client configuration.
whoami
GET /plans, for one plan, with archived plans excluded. Returns a Whoami with baseUrl (str) and agencyId (str, or None when the API does not name an agency). It is free and retried like a read. See Checking the key at startup.
Plans
submit, update, and replace log one line for each kind of API warning on the kardinal logger, at the WARNING level. Python prints these lines on stderr even if you set up no logging. To silence them, call logging.getLogger("kardinal").setLevel(logging.ERROR). To read the warnings in your program, use the .warnings attribute of the returned Plan. See Warnings on successful calls.
plans.submit
POST /plans. Creates the plan and starts its optimization. Returns the stored Plan, with the id the server assigned and .warnings. Raises UnknownFieldError, before sending, for a key no model declares, unless named in allow_unknown. Consumes credits with a production key. Never retried.
plans.get
GET /plans/{planId}. Returns the plan as currently stored. Raises KardinalNotFoundError if it doesn’t exist.
plans.update
PUT /plans/{planId}. Replaces the whole plan: anything left out is removed. The version increments, and the plan is re-optimized, only if the content changed; an identical update is a free no-op. Fields unknown to this SDK version that get read are sent back untouched; a key you added that no model declares raises UnknownFieldError, unless named in allow_unknown. On a plan not read from the API, a likely typo only emits an UnknownFieldWarning. force=True unarchives an archived plan first. Retried.
plans.replace
PUT /plans/{planId}. Replaces the whole plan from a PlanCreate, the input that submit takes. You have no id, agencyId, or version to copy. A field that the API gained after this SDK version is removed, so use get and update when you need to keep it. A Plan that you read with get raises TypeError before any request. An identical plan is a free no-op and keeps the same version. A plan created from raw JSON gets one new version the first time. There is no version check, so the last write wins. Raises UnknownFieldError as submit does. force=True unarchives an archived plan first. Retried. See Replacing a plan from your own data.
plans.delete
DELETE /plans/{planId}. Permanently deletes the plan and its solution, and stops any optimization in progress. Retried.
plans.list
GET /plans. Returns one page of plans, in their light form. A page past the last one returns the last page.
plans.iter_all
GET /plans, every page. Iterates over every plan, fetching pages as it goes.
plans.start
PUT /plans/{planId}/running. Restarts the optimization of the current version, without changing its content or version. Returns agencyId, planId, planVersion, and warnings. Retried.
plans.stop
PUT /plans/{planId}/running. Stops the optimization in progress, without changing the plan’s content or version. Retried.
plans.get_status
GET /plans/{planId}/state. Returns the plan’s current state, a single value: waiting, processing, optimizing, optimized, stopped, interrupted, and so on. It always returns a PlanState, even for a state this SDK version doesn’t know yet: that state comes back as a PlanState that equals its raw string. Not the detailed PlanStatus object found in Plan.status.
Solutions
solutions.wait
GET /plans/{planId}/state, then /solution. Blocks until the optimization of the current version is over, then returns its solution. Reads the state every 10 seconds at first, up to every 60 seconds. solution.final_state tells how it ended: optimized, interrupted, or stopped. Raises KardinalOptimizationError (NO_SOLUTION, PLAN_SUPERSEDED, OPTIMIZATION_STALLED), KardinalNotFoundError if the plan is deleted meanwhile, and KardinalTimeoutError once timeout seconds have elapsed. See Waiting for the solution.
solutions.get
GET /plans/{planId}/solution. Returns the current best solution right away, without waiting. Raises KardinalNotFoundError until the engine has a first solution.
solutions.get_objectives
GET /plans/{planId}/solution/objectives. Returns the value of each objective, without the tours: a plain list of SolutionObjective, with a .warnings attribute.
Solution fields
solution.tours holds one Tour per resource used. tour.wayPoints is a list of WayPointBegin, WayPointStop, WayPointBreak, and WayPointEnd objects, from kardinal.routing.models. Read wp.type ("begin", "stop", "break", or "end") before you read a field.
Every field in these tables except type is optional: it is None when the API leaves it out. The SDK returns dates and durations as str and does not convert them.
A date is the local time of the plan’s tz, with its offset and seconds, for example 2026-11-20T08:01:23+01:00. If the plan has no tz, the date is in UTC, with a Z. The solution.timestamp is always in Z. See Dates and time zones. To get a datetime, write datetime.fromisoformat(value.replace("Z", "+00:00")), which also works on Python 3.10.
A duration is an ISO 8601 string such as PT5H11M55S. The Python standard library has no parser for it.
The span of a break waypoint, from
arrivalTime to departureTime, can be longer than the break, because it includes any wait before the break. For example, a 30-minute break can show 10:10 to 12:30. See Breaks.
solution.totalDelay sums the delays, and solution.unaffectedStopIds lists the stops left out. Capacities, violations, and properties are in the API Reference.
Examples
examples.small_delivery_plan
examples.cold_chain_plan
examples.parcel_express_plan
Local checks
unknown_fields
submit makes, without sending anything: every key no model declares, with its path and, when one is close, the real field name it was likely meant to be. Empty when the plan is clean.
Types
PlanCreate
From kardinal.routing.plans. The plan you submit: no id, the server assigns it. Built from kardinal.routing.models objects, or loaded from JSON with PlanCreate.model_validate_json(text). Its orders are kardinal.routing.plans.Order objects.
Plan
From kardinal.routing.plans. The plan as stored, returned by submit, get, update, and replace: the same content plus id, version, status, state, and agencyId, and .warnings from the call that returned it.
Page
From kardinal. Returned by plans.list: items, page, total_pages, total, next_page (None on the last page), previous_page (None on the first page), and items_per_page.
Model types
kardinal.routing.models holds a pydantic model for every schema of the API specification (Resource, SingleStop, AlternativesStop, Position, TimeWindow, Solution, Tour, Warning, and so on), with the API’s field names and descriptions.
Exceptions
All importable fromkardinal, all subclasses of KardinalError. See Errors, retries, and warnings.
UnknownFieldWarning, also importable from kardinal, is a warning, not an exception: see Client-side errors.
Every exception carries .code, .status, .errors, .details, .retryable, .warnings, and .request_id.
Known limitations
- The client is synchronous; there’s no
asyncioclient. pydanticconverts a string holding a number or a boolean ("1","true") instead of refusing it..request_idis usuallyNone: the API sends anX-Request-Idheader only on some responses.- The
kardinalcommand needs thecliextra:pip install "kardinal-ai[cli]".

