Start real background planning job

Independent locks default false; include_planned defaults false. Feasibility still accounts for existing work. Select eligible assigned vans; window/hours/duty constraints remain strict. Job updates planning versions only; publication is explicit. No usable result preserves current planning plan. Integration permission: planning.run. Administrator membership grants management access only to this business.

Authentication

Authorized business administrator session, or a business API key with planning.run.

Parameters

Request

Example JSON body

{
  "vehicle_ids": [
    "van-01"
  ],
  "date_start": "2026-11-02",
  "date_end": "2026-11-02",
  "dates": [
    "2026-11-02"
  ],
  "schedule_lock": false,
  "assignment_lock": false,
  "include_planned": false,
  "objectives": [
    "completed_tasks",
    "travel"
  ]
}

{
  "$ref": "#/components/schemas/PlanningRequest"
}

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/planning/preview' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"vehicle_ids":["van-01"],"date_start":"2026-11-02","date_end":"2026-11-02","dates":["2026-11-02"],"schedule_lock":false,"assignment_lock":false,"include_planned":false,"objectives":["completed_tasks","travel"]}'

Responses

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

202 · Successful response

application/json

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "status": "example"
}

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string"
    }
  }
}

401 · Missing/invalid/revoked token

application/json

{
  "error": {
    "code": "unauthorized",
    "message": "Missing/invalid/revoked token"
  }
}

{
  "$ref": "#/components/schemas/Error"
}

403 · Business membership or required API-key scope denied

application/json

{
  "error": {
    "code": "unauthorized",
    "message": "Business membership or required API-key scope denied"
  }
}

{
  "$ref": "#/components/schemas/Error"
}

404 · Record not found in authorized business

application/json

{
  "error": {
    "code": "not_found",
    "message": "Record not found in authorized business"
  }
}

{
  "$ref": "#/components/schemas/Error"
}

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

application/json

{
  "error": {
    "code": "conflict",
    "message": "Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity"
  }
}

{
  "$ref": "#/components/schemas/Error"
}

422 · Domain validation rejected the operation

application/json

{
  "error": {
    "code": "validation",
    "message": "Domain validation rejected the operation"
  }
}

{
  "$ref": "#/components/schemas/Error"
}

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

application/json

{
  "error": {
    "code": "unavailable",
    "message": "Required persistence, map/routing or other infrastructure unavailable"
  }
}

{
  "$ref": "#/components/schemas/Error"
}