route.

API REFERENCE

Read authorized business settings

GET/api/v1/businesses/{id}/settings

Read the selected business name, IANA time zone, and operational settings. Requires an administrator account with membership in that business; settings are isolated from every other business.

Authentication

Requires an authorized administrator bearer session; business membership rules apply. Do not assume an integration key can replace an account session.

Parameters

ParameterInTypeDescription
idRequiredpathstringBusiness ID must belong to the authenticated administrator.Format: uuid

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/businesses/11111111-1111-4111-8111-111111111111/settings' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --output response.bin

Responses

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

200 · Selected business settings. Zone changes preserve existing UTC appointment instants.

application/json

FieldTypeDescription & constraints
idstringIdentifier unique within its authorized business. Some create operations generate it when omitted.
nameRequiredstringHuman-readable name shown in the workspace.
time_zoneRequiredstringResource-specific value; see the related workflow and schema.
planningobjectBusiness planning preferences.
evidenceobjectShared completion-evidence requirements.
routingobjectLocal road-routing engine and approved-dataset update schedule.
planning fields
FieldTypeDescription & constraints
planning.travel_metrictime | distance | nullResource-specific value; see the related workflow and schema.
planning.objectivesarray<completed_tasks | travel>Planning objectives; completing more work and minimizing travel can be combined.
planning.location_freshness_secondsintegerResource-specific value; see the related workflow and schema.
planning.min_rest_secondsinteger | nullResource-specific value; see the related workflow and schema.
planning.notify_unplannedbooleanResource-specific value; see the related workflow and schema.
evidence fields
FieldTypeDescription & constraints
evidence.require_photosbooleanResource-specific value; see the related workflow and schema.
evidence.require_signaturebooleanResource-specific value; see the related workflow and schema.
routing fields
FieldTypeDescription & constraints
routing.engineosrm | valhallaResource-specific value; see the related workflow and schema.
routing.update_schedulestringFive-field cron in business time zone. Weekly Sunday03:00 default; approved regions only.
Illustrative response
{
  "id": "example-id",
  "name": "Example Services",
  "time_zone": "Europe/Warsaw",
  "planning": {
    "travel_metric": "time",
    "objectives": [
      "completed_tasks",
      "travel"
    ],
    "location_freshness_seconds": 1,
    "min_rest_seconds": 1,
    "notify_unplanned": false
  },
  "evidence": {
    "require_photos": false,
    "require_signature": false
  },
  "routing": {
    "engine": "osrm",
    "update_schedule": "example"
  }
}
Response schema
{
  "$ref": "#/components/schemas/OperationalSettings"
}

400 · Axum extraction rejects invalid JSON/type, oversized body, or malformed UUID before the domain handler. These responses may be text/plain rather than the domain Error object.

text/plain

Binary response. Save the returned bytes to a file; do not parse as JSON.

401 · Invalid credentials, missing bearer token, or expired/unverified session.

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid credentials, missing bearer token, or expired/unverified session."
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

404 · Business absent or not authorized for this account; no cross-business existence disclosure.

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "not_found",
    "message": "Business absent or not authorized for this account; no cross-business existence disclosure."
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}

503 · Required persistence or credential operation unavailable.

application/json

FieldTypeDescription & constraints
errorRequiredobjectResource-specific value; see the related workflow and schema.
error fields
FieldTypeDescription & constraints
error.codeRequiredvalidation | unauthorized | not_found | conflict | unavailable | rate_limitedPrivate activation or recovery code supplied to the driver.
error.messageRequiredstringResource-specific value; see the related workflow and schema.
Illustrative response
{
  "error": {
    "code": "unavailable",
    "message": "Required persistence or credential operation unavailable."
  }
}
Response schema
{
  "$ref": "#/components/schemas/Error"
}
← All endpointsIntegration workflows →