route.

API REFERENCE

Run actual graph pathfinding/scheduling

POST/api/v1/businesses/{id}/scenarios/{scenario}/run

Trace events are real engine events. Unsupported layers are declared unavailable, never fabricated. Graph points may have explicit directional edge-segment weights. Integration permission: scenarios.read. Administrator membership grants management access only to this business.

Authentication

Authorized business administrator session, or a business API key with scenarios.read.

Parameters

ParameterInTypeDescription
idRequiredpathstringAuthorized business context. Never inferred from client record IDs.Format: uuid
scenarioRequiredpathstring

Request

FieldTypeDescription & constraints
tracebooleanResource-specific value; see the related workflow and schema.

Example JSON body

{
  "trace": false
}
Request schema
{
  "type": "object",
  "properties": {
    "trace": {
      "type": "boolean"
    }
  }
}

Example request

Replace synthetic identifiers and credentials. Example dates, coordinates, revisions, and IDs are not production defaults. Read the workflow guide before making a write.

curl --request POST 'https://route-api.okok.space/api/v1/businesses/11111111-1111-4111-8111-111111111111/scenarios/scenario-01/run' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"trace":false}'

Responses

Examples illustrate the documented shape; optional fields and current state can differ. JSON extraction/body-limit errors may be plain text.

200 · Successful response

application/json

FieldTypeDescription & constraints
routesarray<object>Resource-specific value; see the related workflow and schema.
unplannedarray<string>Resource-specific value; see the related workflow and schema.
eventsarray<object>Subscribed event names; use * for all supported events.
trace_capabilitiesobjectResource-specific value; see the related workflow and schema.
routes[] fields
FieldTypeDescription & constraints
routes.idRequiredstringIdentifier unique within its authorized business. Some create operations generate it when omitted.
routes.vehicle_idRequiredstringAssigned or selected vehicle ID in this business.
routes.driver_idstring | nullAssigned driver ID; stop-specific assignments can change after a handover.
routes.revisionRequiredintegerCurrent version used to detect stale edits or publication.
routes.stateRequiredplanning | published | supersededPlanning/published version state or event visibility state.
routes.start_atstringRFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
routes.end_atstringRFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
routes.stopsRequiredarray<object>Ordered planned route stops.
routes.return_legobjectResource-specific value; see the related workflow and schema.
routes.warningsarray<string>Constraint warnings requiring review where applicable.
routes.unplanned_order_idsarray<string>Resource-specific value; see the related workflow and schema.
routes.publishedobject | nullResource-specific value; see the related workflow and schema.
routes.received_atstring | nullResource-specific value; see the related workflow and schema.
events[] fields
FieldTypeDescription & constraints
events.sequenceintegerResource-specific value; see the related workflow and schema.
events.kindstringPhoto or customer signature evidence.
events.detailsobjectResource-specific value; see the related workflow and schema.
trace_capabilities fields
FieldTypeDescription & constraints
trace_capabilities.pathfindingbooleanResource-specific value; see the related workflow and schema.
trace_capabilities.schedulingbooleanResource-specific value; see the related workflow and schema.
Illustrative response
{
  "routes": [
    {
      "id": "example-id",
      "vehicle_id": "van-01",
      "driver_id": "driver-01",
      "revision": 1,
      "state": "planning",
      "start_at": "2026-11-02T08:00:00Z",
      "end_at": "2026-11-02T16:00:00Z",
      "stops": [
        {}
      ],
      "return_leg": {},
      "warnings": [
        "example"
      ],
      "unplanned_order_ids": [
        "example"
      ],
      "published": {},
      "received_at": "2026-11-02T09:00:00Z"
    }
  ],
  "unplanned": [
    "example"
  ],
  "events": [
    "*"
  ],
  "trace_capabilities": {
    "pathfinding": false,
    "scheduling": false
  }
}
Response schema
{
  "type": "object",
  "properties": {
    "routes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Plan"
      }
    },
    "unplanned": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sequence": {
            "type": "integer"
          },
          "kind": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "trace_capabilities": {
      "type": "object",
      "properties": {
        "pathfinding": {
          "type": "boolean"
        },
        "scheduling": {
          "type": "boolean"
        }
      }
    }
  }
}

401 · Missing/invalid/revoked token

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "unauthorized",
    "message": "Missing/invalid/revoked token"
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

403 · Business membership or required API-key scope denied

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "unauthorized",
    "message": "Business membership or required API-key scope denied"
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

404 · Record not found in authorized business

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "not_found",
    "message": "Record not found in authorized business"
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "conflict",
    "message": "Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity"
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

422 · Domain validation rejected the operation

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "validation",
    "message": "Domain validation rejected the operation"
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

503 · Required persistence, map/routing or other infrastructure unavailable

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "unavailable",
    "message": "Required persistence, map/routing or other infrastructure unavailable"
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}
← All endpointsIntegration workflows →