First API call - Kardinal API

Kardinal’s Always-on Route Optimization API (ARO) works around two steps: you submit a plan (vehicles, orders, constraints), and you retrieve the solution the engine computes for it. This tutorial walks through both, using the smallest possible plan.

AI agent modeling a real client’s data, not just running this tutorial? See Start here if you’re an AI agent first — this tutorial’s minimal plan skips several decisions (capacity feasibility, hard vs. soft time windows) that matter as soon as you’re working from real data.

Access to the API is provisioned by invitation: you’re invited to set a password for a username (usually your company email), and given an environment URL that looks like https://<env>.kardinal.ai (for example https://app.kardinal.ai). There is currently no self-serve sign-up flow — if you don’t have credentials yet, contact your Account Executive or api@kardinal.ai.

Step 1 — Authenticate

Kardinal uses JWT authentication. Exchange your username and password for an access_token:

curl -X POST "https://<env>.kardinal.ai/api/v2/login" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"username":"<username>","password":"<password>"}'

Response

{
  "access_token": "<token>",
  "refresh_token": "<refresh_token>",
  "user": { ... }
}

Keep the access_token — every following request uses it as a bearer token. It’s valid for one hour; see Authentication and API keys for how to refresh it.

Step 2 — Submit a minimal plan

A plan is created with a single PUT request (this doubles as create and update — see How the optimization engine works). Here is the smallest viable plan: one resource and three pickup-only orders in Paris.

curl -X PUT "https://<env>.kardinal.ai/api/v2/agencies/<your_agency>/plans/test_plan" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
  "id": "test_plan",
  "agencyId": "<your_agency>",
  "version": 1,
  "resources": [
    {
      "id": "resource1",
      "vehicleProfile": { "type": "fly", "kmph": 20 },
      "workingTimeWindow": { "begin": "2023-03-21T08:00:00Z", "end": "2023-03-21T23:00:00Z" }
    }
  ],
  "orders": [
    { "id": "order-1", "stops": [{ "type": "single", "id": "Balard", "position": { "lon": 2.279424, "lat": 48.835749 }, "kind": "pickup", "operationDuration": "PT5M30S" }] },
    { "id": "order-2", "stops": [{ "type": "single", "id": "Dauphine", "position": { "lon": 2.274264, "lat": 48.870087 }, "kind": "pickup", "operationDuration": "PT5M30S" }] },
    { "id": "order-3", "stops": [{ "type": "single", "id": "Station-f", "position": { "lon": 2.370564, "lat": 48.83476 }, "kind": "pickup", "operationDuration": "PT5M30S" }] }
  ],
  "maxOptimizationDuration": "PT1M"
}'

"type": "fly" is a crow-fly vehicle profile — it’s fast to compute and ideal for a first test. Real integrations typically use car or truck profiles (see the data model reference).

You can also submit a plan as a file upload (-F "file=@plan.json") instead of an inline -d body, and as XLSX instead of JSON — column names in the spreadsheet match the JSON field names. As soon as the plan is accepted, optimization starts automatically — there’s no separate “start” call.

Step 3 — Retrieve the solution

curl "https://<env>.kardinal.ai/api/v2/agencies/<your_agency>/plans/test_plan/solution" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token>"

The response wraps the result in an item field and gives you, per resource, the ordered list of stops (tours[].wayPoints) with arrival/departure times, plus any stop that couldn’t be planned:

Response (abridged)

{
  "item": {
    "planId": "test_plan",
    "planVersion": 1,
    "unaffectedStopIds": [],
    "unusedResourceIds": [],
    "tours": [
      {
        "resourceId": "resource1",
        "distanceInKm": 10.509,
        "workingDuration": "PT25M16S",
        "wayPoints": [
          { "type": "stop", "stopId": "Station-f", "arrivalTime": "2023-03-21T08:00:00Z", "stopKind": "pickup" },
          { "type": "stop", "stopId": "Balard", "arrivalTime": "2023-03-21T08:11:04Z", "stopKind": "pickup" },
          { "type": "stop", "stopId": "Dauphine", "arrivalTime": "2023-03-21T08:19:46Z", "stopKind": "pickup" }
        ]
      }
    ]
  }
}

For a small test plan like this one, the solution is typically ready within seconds — for larger plans, poll the plan’s status field until optimization settles (see the polling workflow in How the optimization engine works).

Next steps

Update test_plan again with the same id to see interactive re-optimization in action — read How the optimization engine works first to understand what happens on update.
Add time windows, capacities, and skills to your orders and resources — see the full data model reference.
Move from crow-fly (fly) to a real vehicle profile (car, truck) before going further than a smoke test.

​Step 1 — Authenticate

​Step 2 — Submit a minimal plan

​Step 3 — Retrieve the solution

​Next steps

Step 1 — Authenticate

Step 2 — Submit a minimal plan

Step 3 — Retrieve the solution

Next steps