Kardinal Webhook API

openapi: 3.2.0
info:
  title: Kardinal Route Optimization Webhook API
  version: 1.0.1
  description: 'This document specifies the REST API of Kardinal for builder users.


    Every endpoint applies to the single agency carried by the access token (either the sandbox agency or the production agency), which is why no agency id appears in the paths. An access token that does not grant access to exactly one agency is rejected with a `403`.


    This single-agency shape is specific to **builder** users, the audience of this document. A builder account is created through self-service sign-up and always has exactly two agencies, `sandbox` and `production` — one per environment. This differs from a **standard** Kardinal user, who may belong to a pre-existing set of agencies of any size and receives a single access token scoped accordingly, rather than one token per environment.


    A `429` response with an empty body signals a temporary overload, not a quota: retry after a pause, with an increasing delay between attempts. See Limits and quotas.


    ## Terminology


    A few everyday terms map to specific fields in this API. Reusing the API''s own vocabulary in integration code and support requests avoids ambiguity:


    - **Route:** the ordered sequence of stops a single resource performs within a plan''s solution. Called a `tour` in the API response (`item.tours[]`, with `resourceId`, `distanceInKm`, `workingDuration`, and `wayPoints`). "Route" is the everyday term; `tour` is the field name you''ll see in payloads.

    - **Route plan** (or just "plan"): the full request submitted for optimization (`resources`, `orders`, and any plan-level constraints or objectives). Called `Plan` in this API. Submitting a plan doesn''t return a route directly; it returns a `Solution` object (under `item`) containing one tour per resource.

    - **Disruption:** an event during execution that invalidates part of an already-computed solution and calls for a new one: a delay, a cancellation, or an urgent new order, typically. A disruption is handled by re-optimizing the affected plan (see "Re-optimization" below), not by starting a new one.

    - **Re-optimization:** submitting an update to a plan that already has a solution (`PUT /plans/{planId}`), using the *same* `id` (the `version` is incremented, and the plan re-optimized, only if its content changed; a `PUT` identical to the stored plan changes nothing and isn''t billed). The engine treats this as "same problem, updated data" (the update still carries the complete plan, not only the changes): it repairs the previous solution, adjusting it just enough to be valid for the new data, then keeps improving from there, rather than searching from scratch.

    - **Delivery window:** the time window during which a `delivery`-kind stop should or must be visited: `authorizedTimeWindows` (hard: outside of it, the stop can''t be planned at all) or `preferredTimeWindows` (soft: reachable outside it, at the cost of the `minimizeDelay` objective).'
  contact:
    url: https://kardinal.ai/
    email: customer.success@kardinal.ai
servers:
- url: https://app.kardinal.ai/api/v2
  description: Production and sandbox (same host; the API token used determines which agency a call applies to).
- url: /api/v2
  description: Relative path, for environments where the host is supplied separately.
security:
- access_token: []
tags:


# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kardinal/refs/heads/main/openapi/kardinal-webhook-api-openapi.yml