PATCH /api/v1/businesses/{id}/plans/{record_id}

PATCH/api/v1/businesses/{id}/plans/{record_id}

This is a managed resource: generic creation or updates are rejected. Use the dedicated workflow. Resource-dependent: orders.read/write; schemas=settings.read/write; drivers=accounts.manage; webhooks=integrations.manage; scenarios=scenarios.read/write; plans=planning.read; others=resources.read/write. PUT/PATCH merge supplied editable fields; system identity/metadata and actual execution timestamps cannot be overwritten. Deleted records are read-only; delete actions use soft deletion and enforce active-work/publication protections. Working-hour updates use the preview/apply workflow. Driver deactivation immediately revokes business-specific access without changing active work.

Managed resource: use its dedicated workflow. Generic writes are not a supported way to create or edit this record.

Authentication

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

Parameters

Parameter	In	Type	Description
`id`Required	path	`string`	Authorized business context. Never inferred from client record IDs.Format: uuid
`record_id`Required	path	`string`

Request

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`revision`Required	`integer`	Current version used to detect stale edits or publication.
`state`Required	`planning \| published \| superseded`	Planning/published version state or event visibility state.
`start_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`end_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`stops`Required	`array<object>`	Ordered planned route stops.
`return_leg`	`object`	Resource-specific value; see the related workflow and schema.
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`unplanned_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`published`	`object \| null`	Resource-specific value; see the related workflow and schema.
`received_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

Example JSON body

{
  "id": "plan-01",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "revision": 1,
  "state": "planning",
  "stops": []
}

Request schema

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

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 PATCH 'https://route-api.okok.space/api/v1/businesses/11111111-1111-4111-8111-111111111111/plans/job-1001' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"id":"plan-01","vehicle_id":"van-01","driver_id":"driver-01","revision":1,"state":"planning","stops":[]}'

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

Field	Type	Description & constraints
`id`	`string`	Optional on creation; generated if absent. Unique within authorized business; duplicates409 even if payload matches.Max length: 120
`type`	`task \| break`	Record or field type; choose one of the listed values.
`location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.
`duration_seconds`Required	`integer`	Time needed to do the work, excluding travel, in seconds.Min: 1
`window_start`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`window_end`Required	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled`	Live execution status. Administrator changes become pending_status until publication.
`pending_status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled \| null`	Resource-specific value; see the related workflow and schema.
`scheduled_at`	`string \| null`	Planned service-start instant; absence indicates unplanned work.
`vehicle_id`	`string \| null`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`replacement_driver_id`	`string \| null`	Administrator-selected replacement driver for a handover break.
`custom_fields`	`object`	Values keyed by the business-defined custom field IDs. Existing orders retain their schema version.
`schema_snapshot`	`object`	Immutable field definition/type/permission version for this order.Response only
`actual_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`actual_completed_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

location fields

Field	Type	Description & constraints
`location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`warehouse_id`Required	`string`	Warehouse used as this vehicle’s route origin/return location.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`color`	`string`	Resource-specific value; see the related workflow and schema.
`height_meters`	`number \| null`	Resource-specific value; see the related workflow and schema.
`weight_kg`	`number \| null`	Resource-specific value; see the related workflow and schema.
`working_hours`	`object`	Vehicle availability: weekly weekday intervals plus calendar-date overrides.

working_hours fields

Field	Type	Description & constraints
`working_hours.weekly`Required	`object`	0=Monday through6=Sunday
`working_hours.overrides`Required	`object`	Calendar-date keys replace that entire date, including prior-night carryover. Empty array means unavailable.
`working_hours.gap_policy`	`return_to_warehouse \| wait`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`email`Required	`string`	Account email address.Format: email
`active`	`boolean`	Whether this account or integration is enabled.
`duty_status`	`online \| offline`	Resource-specific value; see the related workflow and schema.
`location`	`object \| null`	Service or record location, using latitude/longitude in decimal degrees.
`duty_started_at`	`string \| null`	Resource-specific value; see the related workflow and schema.
`activation_code`	`string`	Returned once during provisioning/reset; administrator delivers it to driver.Response only

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`location`Required	`object`	Service or record location, using latitude/longitude in decimal degrees.

location fields

Field	Type	Description & constraints
`location.latitude`Required	`number`	Latitude in decimal degrees, from -90 to 90.Min: -90 · Max: 90
`location.longitude`Required	`number`	Longitude in decimal degrees, from -180 to 180.Min: -180 · Max: 180

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`fields`Required	`array<object>`	Custom-field definitions captured for new orders.

fields[] fields

Field	Type	Description & constraints
`fields.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`fields.name`Required	`string`	Human-readable name shown in the workspace.
`fields.type`Required	`text \| number \| date \| datetime \| boolean \| select`	Record or field type; choose one of the listed values.
`fields.required`	`boolean`	Whether a value is mandatory.
`fields.driver_visible`	`boolean`	Whether drivers can see the field.
`fields.driver_editable`	`boolean`	Whether drivers can edit the field; hidden fields cannot be editable.
`fields.multiple`	`boolean`	Allow multiple dropdown choices when true.
`fields.choices`	`array<object>`	Allowed dropdown options with stable IDs and labels.

fields.choices[] fields

Field	Type	Description & constraints
`fields.choices.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`fields.choices.label`Required	`string`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`url`Required	`string`	HTTPS destination for webhook deliveries.Format: uri
`events`Required	`array<string>`	Subscribed event names; use * for all supported events.
`active`	`boolean`	Whether this account or integration is enabled.
`secret`	`string`	Private shared webhook-signing secret.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`geometry`Required	`object`	GeoJSON Polygon; coordinates are longitude/latitude.
`status`	`not_installed \| queued \| running \| installing \| ready \| failed \| building`	Current execution or operation state. Planned/unplanned is separate from execution.
`job_id`	`string \| null`	Resource-specific value; see the related workflow and schema.
`dataset_version`	`string \| null`	Resource-specific value; see the related workflow and schema.
`error`	`string \| null`	Resource-specific value; see the related workflow and schema.

geometry fields

Field	Type	Description & constraints
`geometry.type`	`Polygon`	Record or field type; choose one of the listed values.
`geometry.coordinates`	`array<array<array<number>>>`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`name`Required	`string`	Human-readable name shown in the workspace.
`nodes`Required	`array<object>`	Graph vertices.
`edges`Required	`array<object>`	Directed graph connections with travel costs.
`orders`	`array<object>`	Resource-specific value; see the related workflow and schema.
`warehouses`	`array<object>`	Resource-specific value; see the related workflow and schema.
`vehicles`	`array<object>`	Resource-specific value; see the related workflow and schema.
`drivers`	`array<object>`	Resource-specific value; see the related workflow and schema.

nodes[] fields

Field	Type	Description & constraints
`nodes.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`nodes.x`Required	`number`	Resource-specific value; see the related workflow and schema.
`nodes.y`Required	`number`	Resource-specific value; see the related workflow and schema.

edges[] fields

Field	Type	Description & constraints
`edges.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`edges.from`Required	`string`	Resource-specific value; see the related workflow and schema.
`edges.to`Required	`string`	Resource-specific value; see the related workflow and schema.
`edges.time_seconds`Required	`number`	Resource-specific value; see the related workflow and schema.
`edges.distance_meters`Required	`number`	Resource-specific value; see the related workflow and schema.
`edges.bidirectional`	`boolean`	Resource-specific value; see the related workflow and schema.
`edges.reverse_time_seconds`	`number`	Resource-specific value; see the related workflow and schema.
`edges.reverse_distance_meters`	`number`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`revision`Required	`integer`	Current version used to detect stale edits or publication.
`state`Required	`planning \| published \| superseded`	Planning/published version state or event visibility state.
`start_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`end_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`stops`Required	`array<object>`	Ordered planned route stops.
`return_leg`	`object`	Resource-specific value; see the related workflow and schema.
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`unplanned_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`published`	`object \| null`	Resource-specific value; see the related workflow and schema.
`received_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`created_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`updated_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`revision`	`integer`	Current version used to detect stale edits or publication.
`deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

Illustrative response

{
  "id": "plan-01",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "revision": 1,
  "state": "planning",
  "stops": []
}

Response schema

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

401 · Missing/invalid/revoked token

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-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

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-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

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-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

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-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

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-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

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-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 endpoints Integration workflows →

Update plans

Authentication

Parameters

Request

Example JSON body

Example request

Responses

200 · Successful response

401 · Missing/invalid/revoked token

403 · Business membership or required API-key scope denied

404 · Record not found in authorized business

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

422 · Domain validation rejected the operation

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