POST /api/v1/businesses/{id}/working-hours/preview

POST/api/v1/businesses/{id}/working-hours/preview

Calendar override replaces prior-night carryover. Apply requires explicit acceptance of affected-order unscheduling; no auto replan. Protected in-progress orders remain unchanged. Capacity releases immediately; route changes remain unpublished. Integration permission: resources.write. Administrator membership grants management access only to this business.

Authentication

Authorized business administrator session, or a business API key with resources.write.

Parameters

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

Request

Field	Type	Description & constraints
`vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`working_hours`Required	`object`	Vehicle availability: weekly weekday intervals plus calendar-date overrides.
`accepted`	`boolean`	Confirm the displayed working-hours impact before applying.
`vehicle_revision`	`integer`	Vehicle revision returned by working-hours preview.
`preview_epoch`	`integer`	Business capacity snapshot returned by preview; apply must match current epoch.

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.

Example JSON body

{
  "vehicle_id": "van-01",
  "working_hours": {
    "weekly": {
      "0": [
        {
          "start": "08:00",
          "end": "17:00"
        }
      ]
    },
    "overrides": {}
  }
}

Request schema

{
  "type": "object",
  "properties": {
    "vehicle_id": {
      "type": "string"
    },
    "working_hours": {
      "$ref": "#/components/schemas/WorkingHours"
    },
    "accepted": {
      "type": "boolean"
    },
    "vehicle_revision": {
      "type": "integer"
    },
    "preview_epoch": {
      "type": "integer",
      "description": "Business capacity snapshot returned by preview; apply must match current epoch."
    }
  },
  "required": [
    "vehicle_id",
    "working_hours"
  ]
}

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/working-hours/preview' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"vehicle_id":"van-01","working_hours":{"weekly":{"0":[{"start":"08:00","end":"17:00"}]},"overrides":{}}}'

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
`affected_orders`	`array<object>`	Resource-specific value; see the related workflow and schema.
`affected_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`vehicle_revision`	`integer`	Vehicle revision returned by working-hours preview.
`preview_epoch`	`integer`	Capacity snapshot returned by working-hours preview; must still match at apply.

affected_orders[] fields

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

affected_orders.location fields

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

Illustrative response

{
  "affected_orders": [
    {
      "id": "example-id",
      "type": "task",
      "location": {
        "latitude": 52.2297,
        "longitude": 21.0122
      },
      "duration_seconds": 1800,
      "window_start": "2026-11-02T09:00:00Z",
      "window_end": "2026-11-02T12:00:00Z",
      "status": "created",
      "pending_status": "created",
      "scheduled_at": "2026-11-02T09:30:00Z",
      "vehicle_id": "van-01",
      "driver_id": "driver-01",
      "replacement_driver_id": "example",
      "custom_fields": {},
      "schema_snapshot": {},
      "actual_started_at": "2026-11-02T09:00:00Z",
      "actual_completed_at": "2026-11-02T09:00:00Z"
    }
  ],
  "affected_order_ids": [
    "example"
  ],
  "warnings": [
    "example"
  ],
  "vehicle_revision": 1,
  "preview_epoch": 1
}

Response schema

{
  "type": "object",
  "properties": {
    "affected_orders": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Order"
      }
    },
    "affected_order_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "vehicle_revision": {
      "type": "integer"
    },
    "preview_epoch": {
      "type": "integer"
    }
  }
}

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 →

Preview/apply calendar working-hour change

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