Skip to main content
Reference for 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

A ready-to-submit plan: two resources, eight single-stop orders around central Paris, and a 10-second optimization. The working window starts tomorrow at 8:00. Each call returns a new object.

examples.cold_chain_plan

The plan of the cold-chain last-mile case study, as a typed object that you adapt to your data. Each call returns a new object.

examples.parcel_express_plan

The plan of the parcel express case study, as a typed object that you adapt to your data. Each call returns a new object.

Local checks

unknown_fields

Runs the check 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 from kardinal, 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 asyncio client.
  • pydantic converts a string holding a number or a boolean ("1", "true") instead of refusing it.
  • .request_id is usually None: the API sends an X-Request-Id header only on some responses.
  • The kardinal command needs the cli extra: pip install "kardinal-ai[cli]".