GET /api/v1/driver/refresh

GET/api/v1/driver/refresh

Driver bearer session only. Revoked/deactivated account immediately blocked. Network loss never automatically ends duty. Refresh returns published plans/current execution and successful-refresh time; driver clients should refresh continuously and display last success. Location permission denial blocks work; GPS unavailable with permission granted does not.

Authentication

Requires a driver bearer session. Administrator sessions and integration keys cannot perform this driver action.

Parameters

No path or query parameters.

Request

No JSON request body is required.

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 GET 'https://route-api.okok.space/api/v1/driver/refresh' \
  --header 'Authorization: Bearer REPLACE_WITH_DRIVER_TOKEN'

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
`business`Required	`object`	Resource-specific value; see the related workflow and schema.
`driver`Required	`object`	Resource-specific value; see the related workflow and schema.
`plans`Required	`array<object>`	Resource-specific value; see the related workflow and schema.
`orders`Required	`array<object>`	Resource-specific value; see the related workflow and schema.
`evidence_requirements`	`object`	Resource-specific value; see the related workflow and schema.
`last_refreshed_at`Required	`string`	Resource-specific value; see the related workflow and schema.Format: date-time
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.

business fields

Field	Type	Description & constraints
`business.id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.Format: uuid
`business.name`Required	`string`	Human-readable name shown in the workspace.
`business.time_zone`Required	`string`	Named IANA time zone, validated by the backend.
`business.deleted_at`	`string \| null`	System-managed UTC soft-deletion instant; null for active records.Format: date-time
`business.deleted_by`	`string \| null`	Deletion actor retained for history.Format: uuid

driver fields

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

plans[] fields

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

orders[] fields

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

orders.location fields

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

evidence_requirements fields

Field	Type	Description & constraints
`evidence_requirements.require_photos`	`boolean`	Resource-specific value; see the related workflow and schema.
`evidence_requirements.require_signature`	`boolean`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "business": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example Services",
    "time_zone": "Europe/Warsaw",
    "deleted_at": "2026-11-02T09:00:00Z",
    "deleted_by": "11111111-1111-4111-8111-111111111111"
  },
  "driver": {
    "id": "example-id",
    "name": "Example Services",
    "email": "dispatcher@example.com",
    "active": true,
    "duty_status": "online",
    "location": {
      "latitude": 52.2297,
      "longitude": 21.0122
    },
    "duty_started_at": "2026-11-02T09:00:00Z",
    "activation_code": "example"
  },
  "plans": [
    {
      "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"
    }
  ],
  "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"
    }
  ],
  "evidence_requirements": {
    "require_photos": false,
    "require_signature": false
  },
  "last_refreshed_at": "2026-11-02T09:00:00Z",
  "warnings": [
    "example"
  ]
}

Response schema

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

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 →

Driver refresh

Authentication

Parameters

Request

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