API essentials

The complete HTTP reference for developers building administrative tools, business integrations, and driver clients. Browse every endpoint or download OpenAPI.

Base URL and version

Production: https://route-api.okok.space. Application endpoints begin with /api/v1; health checks live at /health and /ready. A self-hosted installation uses its own API origin. Send JSON with Content-Type: application/json unless a reference page specifies a binary response.

The downloadable OpenAPI contract and generated endpoint pages describe the shipped backend. API and client API are not different servers: client integrations use permitted business endpoints with scoped keys, while administrator and driver identities have distinct access rules.

Authentication and business isolation

Credential	Where to obtain it	Intended use
Administrator session	Verified account → /api/v1/auth/login	Account access and authorized business administration.
Integration API key	Administrator → API keys	Server-to-server business operations within explicitly granted scopes.
Driver session	Activated driver account → /api/v1/driver/login	Dedicated driver execution and map/evidence endpoints only.

Use Authorization: Bearer YOUR_TOKEN. Keep tokens out of URLs, browser bundles, analytics, and public logs. An API key is shown once; save it securely and revoke it when no longer needed. New keys have no access until scopes are granted.

Most business endpoints contain {id}, the authorized business UUID. Order IDs are unique within a business, not globally. A valid token does not grant access to another business. Account-level authentication/settings endpoints can require an administrator session even though operational endpoints accept scoped keys; consult each reference page rather than substituting one credential type for another.

Example administrator login:

curl --request POST 'https://route-api.okok.space/api/v1/auth/login' \
  --header 'Content-Type: application/json' \
  --data '{"email":"dispatcher@example.com","password":"Example-passphrase-42!"}'

Use the returned opaque token; it is not a JWT to decode. Read /api/v1/auth/me to discover businesses accessible to the signed-in administrator. Login examples use synthetic credentials and do not create a shared public account.

Read the endpoint pages

Each endpoint page documents its method/path, description, credential context, API-key scope when supported, path/query parameters, request fields, curl example, and response/error schemas with illustrative examples. Required fields are marked. Nested objects expose their fields. Resource routes expand into explicit orders, vehicles, drivers, warehouses, schemas, webhooks, regions, scenarios, plans, notifications, and administrator entries.

Some generic write routes exist but reject writes to managed records such as plans and notifications. Those pages say so. Use dedicated planning/publication actions instead of trying to write a plan directly. Schemas show possible response fields; illustrative examples are not a guarantee every optional field is returned.

Dates, locations, and units

• Send datetimes in RFC 3339 with an explicit UTC offset, for example 2026-11-02T09:00:00+01:00 or 2026-11-02T08:00:00Z. A timezone-free wall-clock string is not an API instant.
• Business settings use a named IANA zone such as Europe/Warsaw. Weekly hours are interpreted in that business zone. Date-only planning selections use YYYY-MM-DD.
• Locations use { "latitude": 52.2297, "longitude": 21.0122 }. GeoJSON geometry uses [longitude, latitude], in that order.
• Durations and travel times use seconds; distances use meters. Vehicle height uses meters and weight uses kilograms.
• Task windows have full start/end datetimes. Automatic planning and availability require the entire service duration to fit. Overnight windows are valid when the end instant follows the start.

Lists, views, and deleted records

Business list endpoints generally return { "items": [...] }. Supported filters are documented per endpoint; do not assume cursor pagination, arbitrary sorting, or undocumented query options.

For orders/plans, view=planning reads current planning-mode data and view=published reads the last published snapshot. Driver clients use their dedicated published refresh endpoint. Live execution can change after a planning snapshot was created.

Use record_status=active, deleted, or all where supported, with q for text search. Deletes are soft deletion; retained history does not imply that deleted records can still be edited. System-managed created_at, updated_at, deletion fields, and revisions are response metadata.

Errors and retries

Domain errors use this envelope:

{
  "error": {
    "code": "conflict",
    "message": "The requested change conflicts with the current state."
  }
}

HTTP status	Typical meaning	Client behavior
400	Malformed request or extraction failure	Fix the submitted syntax/type.
401	Missing, expired, or revoked authentication	Sign in again or replace the key; do not loop indefinitely.
403	Missing business access or API-key scope	Check membership and granted scope.
404	Record not found in authorized context	Confirm business/record IDs.
409	Duplicate ID, stale revision, expired reservation, or protected publication	Reload current data and resolve the conflict.
422	Domain validation failure	Correct the fields or workflow.
429	Rate limit	Back off before retrying; do not repeatedly submit credentials.
503	Required database, map, routing, or other service unavailable	Retry later with bounded backoff and show pending/error state.

Framework JSON/size errors may return a text body rather than this envelope. Check status and content type before parsing. Authentication/signup/recovery routes are rate limited. There is no general idempotency-key contract: creating the same client-provided order ID again returns a conflict, even when the payload matches. After an ambiguous timeout, inspect current state before repeating a write or reservation confirmation.

Jobs, concurrency, and publication

Planning and map preparation are asynchronous. A successful start returns a job ID; poll the corresponding business job endpoint with bounded backoff and respect failed/completed states. A completed planning run updates planning-mode versions; it does not send work to drivers.

Publication is explicit. Supply the expected plan revisions when publishing reviewed plans. In-progress conflicts can block the entire affected publication. Review manual warnings before sending acknowledge_warnings: true. Follow the integration workflows.