Skip to main content
Reference for @kardinal-ai/sdk 1.3.0, for Node.js 22 or later. Every method below returns a Promise, except plans.iterAll, an async iterator. 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. There’s nothing to close. See Client configuration.

whoami

GET /plans, for one plan, archived plans excluded. Returns Whoami, an object { baseUrl: string; agencyId: string | null }: the host the key was checked against, and the agency the key belongs to. agencyId is null when the API names none. The call is free, and it is retried like a read. See Checking the key at startup.

Plans

plans.submit

POST /plans. Validates the plan locally, then creates it and starts its optimization. Returns the stored Plan, with the id the server assigned and warnings. Throws a ZodError for an invalid plan, and UnknownFieldError for a key no schema declares unless named in allowUnknown, both before sending. Consumes credits with a production key. Never retried. submit, update, and replace pass each kind of warning the API returns to onWarning, as one line with an empty fields array. By default, onWarning is console.warn. To stay quiet, pass onWarning: () => {}. To keep only the typo warnings of update, ignore the calls whose fields array is empty. If your handler fails, the SDK reports the failure with console.error, and the call still returns the plan. A program that needs the warnings reads plan.warnings. See Warnings on successful calls.

plans.get

GET /plans/{planId}. Returns the plan as currently stored. Rejects with 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 schema declares throws UnknownFieldError, unless named in allowUnknown. On a plan this client didn’t read, a likely typo only goes to onWarning. force: true unarchives an archived plan first. Retried.

plans.replace

PUT /plans/{planId}. Replaces the whole plan from a PlanCreateInput, the input submit takes. The input has no id, agencyId, or version to copy. Anything you leave out is removed, including a field the API gained after this SDK version. To keep such a field, use get and update instead. Validates the plan locally first, and throws a ZodError or an UnknownFieldError before any request. allowUnknown names keys to send anyway. An identical plan is a free no-op, and the version stays the same. A plan created from raw JSON gets one new version the first time. There is no version check, so the last write wins. 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; defaults: page 1, 20 items, archived plans excluded. A page past the last one returns the last page.

plans.iterAll

GET /plans, every page. Iterates over every plan with for await, 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.getStatus

GET /plans/{planId}/state. Returns the plan’s current state, a single value: waiting, processing, optimizing, optimized, stopped, interrupted, and so on. A state this SDK version doesn’t know comes back as its raw string. Not the detailed PlanStatus object found in Plan.status.

Solutions

solutions.wait

GET /plans/{planId}/state, then /solution. Resolves once the optimization of the current version is over, with its solution. Reads the state every 10 seconds at first, up to every 60 seconds. solution.finalState tells how it ended: optimized, interrupted, or stopped. Rejects with KardinalOptimizationError (NO_SOLUTION, PLAN_SUPERSEDED, OPTIMIZATION_STALLED), KardinalNotFoundError if the plan is deleted meanwhile, and KardinalTimeoutError once timeoutMs milliseconds have elapsed. See Waiting for the solution.

solutions.get

GET /plans/{planId}/solution. Returns the current best solution right away, without waiting. Rejects with KardinalNotFoundError until the engine has a first solution.

solutions.getObjectives

GET /plans/{planId}/solution/objectives. Returns the value of each objective, without the tours: a plain array of SolutionObjective, with a warnings property.

Solution fields

solution.tours holds one Tour for each resource used. tour.wayPoints is a list of waypoints, and each waypoint has a type: "begin", "stop", "break", or "end". Read wp.type before you read any other field. From 1.3.0, the package exports the four waypoint types by name: WayPointBegin, WayPointStop, WayPointBreak, and WayPointEnd. Narrow a waypoint on wp.type before you read its other fields. The delay field only exists after wp.type === "stop".
Every field in these tables except type is optional, so it is undefined when the API leaves it out. The SDK returns dates and durations as string, without converting 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. Without tz, a date is in UTC, with a Z. solution.timestamp is always in Z. See Dates and time zones. new Date(value) keeps the instant, but not the offset. To show the local time of tz, format the Date with that time zone. A duration is an ISO 8601 string such as PT5H11M55S. JavaScript has no parser for it. A break waypoint runs from arrivalTime to departureTime, and that span 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 of the tours, and solution.unaffectedStopIds lists the stops left out of every tour. Capacities, violations, and properties are in the API Reference.

Examples

examples.smallDeliveryPlan

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

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

examples.parcelExpressPlan

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

Local checks

unknownFields

Runs the check submit makes, without sending anything: every key no schema 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. parsePlanCreate(data, allowUnknown?) runs all of submit’s local checks, zod validation included, and returns the plan with its defaults applied; parsePlan(data) validates a stored plan, such as one read from a file before an update.

Types

PlanCreate

The plan you submit: no id, the server assigns it. PlanCreateInput is the same shape before defaults are applied: the type to use for a plan you build by hand.

Plan

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

Returned by plans.list: items, page, totalPages, total, nextPage (null on the last page), previousPage (null on the first page), and itemsPerPage.

Model types

The package exports a type for the main schemas of the API specification (Resource, SingleStop, AlternativesStop, Position, TimeWindow, Solution, Tour, Warning, and so on), with the API’s field names and descriptions. Import them with import type. From 1.3.0, the four waypoint types are among them: see Solution fields.

Exceptions

All importable from @kardinal-ai/sdk, all subclasses of KardinalError. See Errors, retries, and warnings. A plan that fails local validation throws a ZodError, from zod, instead. Every error carries .code, .status, .errors, .details, .retryable, .warnings, and .requestId.

Known limitations

  • Node.js only: browsers aren’t supported.
  • The inside of the rarer nested objects (cost, breaks, objectives, constraints) isn’t validated locally, and a misspelled key there isn’t reported.
  • update’s exact check of unknown keys needs the plan to have been read by the same client, in the same process; it remembers the last 64 plans.
  • .requestId is usually null: the API sends an X-Request-Id header only on some responses.
  • The kardinal command needs commander installed alongside the package.