Docs

API reference

Every operation an OAuth token can call, with its scope, parameters, request body and responses. It is generated from the API definition openapi.public.json, so it cannot drift from the server.

The reference text of operations and fields below is generated from the API definition and is in English in every language.

Conventions

  • Base URL https://api.stracker.vn. Send Authorization: Bearer <access_token> and, for a body, Content-Type: application/json.
  • Lists take page and limit; most also take searchKeyword. Webhook lists answer { "data": [...], "meta": { ... } }.
  • Writes accept an optional Idempotency-Key header: see idempotency.
  • Errors are application/problem+json with a stable code; see errors.
  • Each operation names the scope it needs. Every call can also answer 401, 403 (OAUTH_INSUFFICIENT_SCOPE, OAUTH_ROUTE_NOT_EXPOSED) and 429 (rate limits).

Drivers

GET/v1/drivers

List drivers (paginated)

Returns a paginated drivers catalog, scoped to the caller's own drivers for Owner permission. Every row carries the server-computed readiness verdict; readiness and unassigned filter on it.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
readinessquerystringValues: drivableblockeddue_soon
unassignedquerystringValues: truefalse
attentionquerystringValues: documentshoursapp
statequerystringValues: drivingreadyrestingonLeaveblockedinactive

Responses

  • 200Paginated driver list
    FieldTypeDescription
    dataobject[]
    data[].namestring
    data[].emailstring
    data[].phonestring
    data[].statusboolean
    data[].typestringValues: parentstudentdriverteacherstaffpassengermotorbike_driver
    data[].descriptionstring
    data[].avatarBase64string
    data[].passwordstringPassword for the driver's linked user account; required only when creating or changing credentialse.g. "Str0ngP@ssw0rd!"
    data[].appAccessbooleanCreate only: true creates the driver-app login (no password; phone-code sign-in, the driver sets one from the app); omitted or false creates no logine.g. false
    data[].licenseStatusstringDerived from license_expiry: valid (>30 days out), expiring_soon (<=30 days), expired, or unknown (no expiry on file, or no driver row exists yet). Read-only, populated only by GET /v1/drivers/:id.e.g. "valid"
    data[].driverIdnumbernullabledriver.id — the identifier every ASSIGNMENT takes (trip.driver_id, route.driver_id, POST /v1/trips/:id/assign). Distinct from this DTO’s id, which is the person.id the driver SCREENS are keyed by. A caller that assigns must send this one: the two spaces do not overlap, and sending a person id answers 404 DRIVER_NOT_FOUND. Absent when the person has no driver row at all, which is exactly the case where they cannot be assigned.e.g. 4
    data[].rowVersionnumberdriver.row_version, bumped by every save of the driver. Send it back as the If-Match header of PUT /v1/drivers/:id to refuse the save when someone else saved the driver in between (409 DRIVER_VERSION_CONFLICT). Populated by GET /v1/drivers/:id and returned by the update.e.g. 3
    data[].licenseExpirystringnullableLicense expiry date (YYYY-MM-DD). Dual-purpose field: readable on every driver response (derived from the driver row's license_expiry), and writable on create/update — SaveDriver persists it to driver.license_expiry whenever the request body supplies it. A PATCH/PUT that omits this field leaves the stored value untouched (partial-update semantics); it is never nulled out implicitly.e.g. "2030-03-01"
    data[].licenseNumberstringLicense number (driver.license_number). Writable on create/update; unique per tenant among non-deleted drivers (uq_driver_license_number) — a collision returns 409 DUPLICATE_ENTRY.e.g. "079203001234"
    data[].licenseClassstringLicense class (driver.license_class), e.g. VN categories A1/A2/B1/B2/C/D/E/F1/F2. Plain string — the DDL column has no native ENUM, so no closed set is enforced. Writable on create/update.e.g. "B2"
    data[].licenseIssueDatestringLicense issue date (YYYY-MM-DD), driver.license_issue_date. Writable on create/update.e.g. "2020-03-01"
    data[].licenseCountrystringCountry/authority that issued the license (driver.license_country) — closest real column to "issuing authority". Writable on create/update.e.g. "VN"
    data[].primaryCampusIdnumbernullablePrimary campus id (driver.primary_campus_id, FK campus.id). Writable on create/update. Omitted leaves the stored value untouched; explicit null clears it. An id that does not exist in the tenant answers 400 VALIDATION_FAILED (field primaryCampusId, code NOT_FOUND). The read-side campus object is derived from this column.e.g. 3
    data[].hosRemainingHoursnumbernullableRemaining hours-of-service today before the driver's max_daily_hours cap. Populated only by GET /v1/drivers/:id.e.g. 4.5
    data[].assignedVehicleIdnumbernullableID of the vehicle assigned via an active route, if any. Populated only by GET /v1/drivers/:id.e.g. 7
    data[].readinessobjectServer-computed readiness verdict. Read-only, populated by GET /v1/drivers and GET /v1/drivers/:id. The FE renders blockers/warnings verbatim and never re-derives canDrive.
    data[].readiness.canDrivebooleanTrue only when blockers is empty.e.g. false
    data[].readiness.blockersobject[]
    data[].readiness.blockers[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    data[].readiness.blockers[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    data[].readiness.blockers[].severitystringValues: blockerwarninge.g. "blocker"
    data[].readiness.blockers[].reasonobject
    data[].readiness.blockers[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Values: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    data[].readiness.blockers[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    data[].readiness.blockers[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    data[].readiness.warningsobject[]
    data[].readiness.warnings[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    data[].readiness.warnings[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    data[].readiness.warnings[].severitystringValues: blockerwarninge.g. "blocker"
    data[].readiness.warnings[].reasonobject
    data[].readiness.warnings[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Values: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    data[].readiness.warnings[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    data[].readiness.warnings[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    data[].licenseobject
    data[].license.classstringnullablee.g. "D"
    data[].license.validUntilstringnullableISO date YYYY-MM-DD.e.g. "2027-03-01"
    data[].license.daysLeftnumbernullableWhole days from today to validUntil; negative when expired, null when no expiry is on file.e.g. 212
    data[].qualificationsobject[]
    data[].qualifications[].idnumbere.g. 12
    data[].qualifications[].codestringThe qualification's licence class — its stable code.e.g. "D"
    data[].qualifications[].namestringDisplay name: the licence class, suffixed with the issuer when one is recorded.e.g. "D — Sở GTVT TP.HCM"
    data[].qualifications[].validUntilstringnullablee.g. "2027-03-01"
    data[].qualifications[].daysLeftnumbernullablee.g. 212
    data[].complianceobject
    data[].compliance.passednumbere.g. 1
    data[].compliance.totalnumbere.g. 2
    data[].compliance.failingstring[]
    data[].hoursobject
    data[].hours.thisWeeknumberOn-duty hours already worked in the current business week.e.g. 32.5
    data[].hours.shiftsThisWeeknumberHow many SHIFTS the driver has in the current business week — a count of shift rows, not hours. Carried separately because the two answer different questions and are not convertible: a client that printed thisWeek under a "shifts" label showed "16.5 shifts".e.g. 6
    data[].hours.byDayobject[]The seven days of the current business week (Monday first), each with the hours worked. Always seven entries, so a day off is a 0 rather than a hole the client has to guess at. Sums to thisWeek — both are derived from the same per-day aggregation.
    data[].hours.byDay[].datestringCalendar day, YYYY-MM-DD.e.g. "2026-09-01"
    data[].hours.byDay[].hoursnumberOn-duty hours worked that day. 0 means a day off, never "unknown".e.g. 8.2
    data[].hours.dailyLimitnumbernullabledriver.max_daily_hours; null means no per-day cap is configured.e.g. 10
    data[].hours.limitnumbernullabledriver.max_weekly_hours; null means no cap is configured and the hours rule is skipped.e.g. 40
    data[].assignmentobjectnullableCurrent active-route assignment, or null when the driver is unassigned.
    data[].assignment.vehicleIdnumbernullablee.g. 7
    data[].assignment.platestringnullablee.g. "51B-123.45"
    data[].assignment.routeLabelstringnullablee.g. "Tuyến 3 — Quận 7"
    data[].availabilityTodaybooleanWhether today falls inside the driver's availability roster.e.g. true
    data[].codestringnullableHuman-readable staff code, e.g. TX-001.e.g. "TX-001"
    data[].campusobjectnullableThe driver's primary campus — the roster's scope label.
    data[].campus.idnumbere.g. 3
    data[].campus.namestringe.g. "THPT Greenfield"
    data[].employmentStatusstringEmployment lifecycle. terminated and on_leave are their own roster row states.Values: activeon_leavesuspendedterminatede.g. "active"
    data[].hireDatestringnullableISO date YYYY-MM-DD.e.g. "2021-08-16"
    data[].requiredDocumentTypesstring[]The papers THIS tenant requires, in display order. Not one list for everybody: school/indep add the child-safety check (wwcc), charter a passenger-carriage certificate (tour), private the dangerous-goods one (adr), transit needs only the universal three. Sent so the client renders the set rather than re-deriving a rule that gates assignment.
    data[].documentsobject[]Required-document strip: one chip per entry of requiredDocumentTypes, in that order, INCLUDING the ones with nothing on file (state pending) — a strip built from existing rows could never show a gap. The licence chip comes from driver.license_expiry, not from a driver_document row.
    data[].documents[].typestringdriver_document.type — the FE maps it to a label.e.g. "licence"
    data[].documents[].statestringexpiring means within 60 days — the same window the attention card counts.Values: validexpiringexpiredpendinge.g. "expiring"
    data[].documents[].validUntilstringnullableISO date YYYY-MM-DD.e.g. "2027-03-01"
    data[].documents[].daysLeftnumbernullablee.g. 41
    data[].shiftobjectnullableToday's rostered shift, or null when nothing is scheduled.
    data[].shift.startsAtstringnullableLocal HH:mm.e.g. "05:00"
    data[].shift.endsAtstringnullableLocal HH:mm; null while the shift is open.e.g. "13:00"
    data[].shift.partstringValues: morningafternoone.g. "morning"
    data[].shift.statusstringValues: openclosedadjustede.g. "open"
    data[].appobjectDriver App connection state.
    data[].app.installedbooleanFalse when last_seen_at was never set — the app has never signed in on this account.e.g. true
    data[].app.onlinebooleanA live app session right now.e.g. false
    data[].app.lastSeenAtstringnullableISO 8601 instant.e.g. "2026-09-01T06:12:00.000Z"
    data[].rowStatestringWhat the driver is DOING today — a different question from readiness.canDrive, which is only whether they may legally take a trip. The roster paints this one.Values: drivingreadyrestingonLeaveblockedinactivee.g. "driving"
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the driver read/write/owner permission
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/drivers/{id}

Get a driver by id

Returns a single driver by primary key.

Parameters

FieldTypeDescription
idpathrequiredintegerThe driver's PERSON id: the id of a GET /v1/drivers row (list_drivers), never its driverId. driverId is the driver.id that trip and route assignment take; sending it here answers 404 DRIVER_PERSON_NOT_FOUND (reason: driver_id_sent) or, when it happens to equal another driver's person id, acts on that other driver.

Responses

  • 200Driver found
    FieldTypeDescription
    namestring
    emailstring
    phonestring
    statusboolean
    typestringValues: parentstudentdriverteacherstaffpassengermotorbike_driver
    descriptionstring
    avatarBase64string
    passwordstringPassword for the driver's linked user account; required only when creating or changing credentialse.g. "Str0ngP@ssw0rd!"
    appAccessbooleanCreate only: true creates the driver-app login (no password; phone-code sign-in, the driver sets one from the app); omitted or false creates no logine.g. false
    licenseStatusstringDerived from license_expiry: valid (>30 days out), expiring_soon (<=30 days), expired, or unknown (no expiry on file, or no driver row exists yet). Read-only, populated only by GET /v1/drivers/:id.e.g. "valid"
    driverIdnumbernullabledriver.id — the identifier every ASSIGNMENT takes (trip.driver_id, route.driver_id, POST /v1/trips/:id/assign). Distinct from this DTO’s id, which is the person.id the driver SCREENS are keyed by. A caller that assigns must send this one: the two spaces do not overlap, and sending a person id answers 404 DRIVER_NOT_FOUND. Absent when the person has no driver row at all, which is exactly the case where they cannot be assigned.e.g. 4
    rowVersionnumberdriver.row_version, bumped by every save of the driver. Send it back as the If-Match header of PUT /v1/drivers/:id to refuse the save when someone else saved the driver in between (409 DRIVER_VERSION_CONFLICT). Populated by GET /v1/drivers/:id and returned by the update.e.g. 3
    licenseExpirystringnullableLicense expiry date (YYYY-MM-DD). Dual-purpose field: readable on every driver response (derived from the driver row's license_expiry), and writable on create/update — SaveDriver persists it to driver.license_expiry whenever the request body supplies it. A PATCH/PUT that omits this field leaves the stored value untouched (partial-update semantics); it is never nulled out implicitly.e.g. "2030-03-01"
    licenseNumberstringLicense number (driver.license_number). Writable on create/update; unique per tenant among non-deleted drivers (uq_driver_license_number) — a collision returns 409 DUPLICATE_ENTRY.e.g. "079203001234"
    licenseClassstringLicense class (driver.license_class), e.g. VN categories A1/A2/B1/B2/C/D/E/F1/F2. Plain string — the DDL column has no native ENUM, so no closed set is enforced. Writable on create/update.e.g. "B2"
    licenseIssueDatestringLicense issue date (YYYY-MM-DD), driver.license_issue_date. Writable on create/update.e.g. "2020-03-01"
    licenseCountrystringCountry/authority that issued the license (driver.license_country) — closest real column to "issuing authority". Writable on create/update.e.g. "VN"
    primaryCampusIdnumbernullablePrimary campus id (driver.primary_campus_id, FK campus.id). Writable on create/update. Omitted leaves the stored value untouched; explicit null clears it. An id that does not exist in the tenant answers 400 VALIDATION_FAILED (field primaryCampusId, code NOT_FOUND). The read-side campus object is derived from this column.e.g. 3
    hosRemainingHoursnumbernullableRemaining hours-of-service today before the driver's max_daily_hours cap. Populated only by GET /v1/drivers/:id.e.g. 4.5
    assignedVehicleIdnumbernullableID of the vehicle assigned via an active route, if any. Populated only by GET /v1/drivers/:id.e.g. 7
    readinessobjectServer-computed readiness verdict. Read-only, populated by GET /v1/drivers and GET /v1/drivers/:id. The FE renders blockers/warnings verbatim and never re-derives canDrive.
    readiness.canDrivebooleanTrue only when blockers is empty.e.g. false
    readiness.blockersobject[]
    readiness.blockers[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    readiness.blockers[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    readiness.blockers[].severitystringValues: blockerwarninge.g. "blocker"
    readiness.blockers[].reasonobject
    readiness.blockers[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Values: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    readiness.blockers[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    readiness.blockers[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    readiness.warningsobject[]
    readiness.warnings[].codestringMachine-readable reason code; the FE maps it to drivers.readiness.<code>.e.g. "LICENSE_EXPIRED"
    readiness.warnings[].labelstringLegacy server-rendered Vietnamese sentence carrying the specifics. Kept for clients that still read it; new clients translate reason instead.e.g. "GPLX đã hết hạn ngày 12/03/2026"
    readiness.warnings[].severitystringValues: blockerwarninge.g. "blocker"
    readiness.warnings[].reasonobject
    readiness.warnings[].reason.codestringStable reason code; the FE maps it to drivers.readiness.reasons.<code>. Finer than the flag code: one category (e.g. COMPLIANCE_FAILED) has several reasons (COMPLIANCE_NOT_FILED, COMPLIANCE_EXPIRED…).Values: DRIVER_INACTIVELICENSE_MISSINGLICENSE_EXPIREDLICENSE_DUE_SOONQUALIFICATION_EXPIREDQUALIFICATION_DUE_SOONCOMPLIANCE_NOT_FILEDCOMPLIANCE_REJECTEDCOMPLIANCE_PENDINGCOMPLIANCE_EXPIREDCOMPLIANCE_NOT_METCOMPLIANCE_DUE_SOONHOURS_EXCEEDEDHOURS_DUE_SOONNOT_AVAILABLE_TODAYCOMPLIANCE_HOLDLICENSE_CLASS_MISSINGLICENSE_CLASS_UNKNOWNLICENSE_CLASS_MISMATCHVEHICLE_CAPACITY_EXCEEDEDVEHICLE_NOT_IN_SERVICEVEHICLE_REGISTRATION_EXPIREDVEHICLE_INSURANCE_EXPIREDVEHICLE_INSPECTION_EXPIREDVEHICLE_REGISTRATION_MISSINGVEHICLE_INSURANCE_MISSINGVEHICLE_INSPECTION_MISSINGe.g. "HOURS_EXCEEDED"
    readiness.warnings[].reason.messagestringDefault English text with the params filled in. A fallback only — clients translate by code.e.g. "Drove 49/48 hours this week"
    readiness.warnings[].reason.paramsobjectInterpolation values for code. Numbers (worked, limit, days, maxSeats, capacity), ISO dates (date), machine values the client words itself (status, vehicleType, document, documents[]), identifiers (plate, licenseClass, names[]) and operator free text (reason).
    licenseobject
    license.classstringnullablee.g. "D"
    license.validUntilstringnullableISO date YYYY-MM-DD.e.g. "2027-03-01"
    license.daysLeftnumbernullableWhole days from today to validUntil; negative when expired, null when no expiry is on file.e.g. 212
    qualificationsobject[]
    qualifications[].idnumbere.g. 12
    qualifications[].codestringThe qualification's licence class — its stable code.e.g. "D"
    qualifications[].namestringDisplay name: the licence class, suffixed with the issuer when one is recorded.e.g. "D — Sở GTVT TP.HCM"
    qualifications[].validUntilstringnullablee.g. "2027-03-01"
    qualifications[].daysLeftnumbernullablee.g. 212
    complianceobject
    compliance.passednumbere.g. 1
    compliance.totalnumbere.g. 2
    compliance.failingstring[]
    hoursobject
    hours.thisWeeknumberOn-duty hours already worked in the current business week.e.g. 32.5
    hours.shiftsThisWeeknumberHow many SHIFTS the driver has in the current business week — a count of shift rows, not hours. Carried separately because the two answer different questions and are not convertible: a client that printed thisWeek under a "shifts" label showed "16.5 shifts".e.g. 6
    hours.byDayobject[]The seven days of the current business week (Monday first), each with the hours worked. Always seven entries, so a day off is a 0 rather than a hole the client has to guess at. Sums to thisWeek — both are derived from the same per-day aggregation.
    hours.byDay[].datestringCalendar day, YYYY-MM-DD.e.g. "2026-09-01"
    hours.byDay[].hoursnumberOn-duty hours worked that day. 0 means a day off, never "unknown".e.g. 8.2
    hours.dailyLimitnumbernullabledriver.max_daily_hours; null means no per-day cap is configured.e.g. 10
    hours.limitnumbernullabledriver.max_weekly_hours; null means no cap is configured and the hours rule is skipped.e.g. 40
    assignmentobjectnullableCurrent active-route assignment, or null when the driver is unassigned.
    assignment.vehicleIdnumbernullablee.g. 7
    assignment.platestringnullablee.g. "51B-123.45"
    assignment.routeLabelstringnullablee.g. "Tuyến 3 — Quận 7"
    availabilityTodaybooleanWhether today falls inside the driver's availability roster.e.g. true
    codestringnullableHuman-readable staff code, e.g. TX-001.e.g. "TX-001"
    campusobjectnullableThe driver's primary campus — the roster's scope label.
    campus.idnumbere.g. 3
    campus.namestringe.g. "THPT Greenfield"
    employmentStatusstringEmployment lifecycle. terminated and on_leave are their own roster row states.Values: activeon_leavesuspendedterminatede.g. "active"
    hireDatestringnullableISO date YYYY-MM-DD.e.g. "2021-08-16"
    requiredDocumentTypesstring[]The papers THIS tenant requires, in display order. Not one list for everybody: school/indep add the child-safety check (wwcc), charter a passenger-carriage certificate (tour), private the dangerous-goods one (adr), transit needs only the universal three. Sent so the client renders the set rather than re-deriving a rule that gates assignment.
    documentsobject[]Required-document strip: one chip per entry of requiredDocumentTypes, in that order, INCLUDING the ones with nothing on file (state pending) — a strip built from existing rows could never show a gap. The licence chip comes from driver.license_expiry, not from a driver_document row.
    documents[].typestringdriver_document.type — the FE maps it to a label.e.g. "licence"
    documents[].statestringexpiring means within 60 days — the same window the attention card counts.Values: validexpiringexpiredpendinge.g. "expiring"
    documents[].validUntilstringnullableISO date YYYY-MM-DD.e.g. "2027-03-01"
    documents[].daysLeftnumbernullablee.g. 41
    shiftobjectnullableToday's rostered shift, or null when nothing is scheduled.
    shift.startsAtstringnullableLocal HH:mm.e.g. "05:00"
    shift.endsAtstringnullableLocal HH:mm; null while the shift is open.e.g. "13:00"
    shift.partstringValues: morningafternoone.g. "morning"
    shift.statusstringValues: openclosedadjustede.g. "open"
    appobjectDriver App connection state.
    app.installedbooleanFalse when last_seen_at was never set — the app has never signed in on this account.e.g. true
    app.onlinebooleanA live app session right now.e.g. false
    app.lastSeenAtstringnullableISO 8601 instant.e.g. "2026-09-01T06:12:00.000Z"
    rowStatestringWhat the driver is DOING today — a different question from readiness.canDrive, which is only whether they may legally take a trip. The roster paints this one.Values: drivingreadyrestingonLeaveblockedinactivee.g. "driving"
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the driver read/write/owner permission
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Not the person id of a live driver of this tenant
    Example
    {
      "type": "https://stracker.io/errors/driver-person-not-found",
      "title": "Driver not found for this person id",
      "status": 404,
      "detail": "Driver not found for this person id",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "DRIVER_PERSON_NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Routes

GET/v1/routes

List routes

Returns a paginated, searchable list of routes, optionally filtered by status or school.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
statusquerystringValues: activeinactivedraftarchived
campusIdqueryinteger
directionqueryinteger

Responses

  • 200Paginated list of routes
    FieldTypeDescription
    dataobject[]
    data[].idnumberRoute ID; 0 or omitted on createe.g. 4
    data[].codestringnullableRoute codee.g. "RT-004"
    data[].namestringRoute display namee.g. "Route A - Morning"
    data[].campusIdnumbernullableID of the school (campus) this route servese.g. 12
    data[].campusNamestringnullableName of the campus this route serves; null when unassigned or not joinede.g. "Greenfield High School"
    data[].vehicleIdnumbernullableID of the vehicle assigned to this routee.g. 7
    data[].vehicleNamestringnullableDisplay name of the assigned vehiclee.g. "B-101"
    data[].vehiclePlatestringnullableRegistration plate of the assigned vehiclee.g. "51F-238.45"
    data[].vehicleCapacitynumbernullableSeats on the assigned vehicle (vehicle.capacity); null when no vehicle or not recordede.g. 45
    data[].vehicleReadinessobjectnullableDispatch verdict of the assigned vehicle (detail read only); null when no vehicle is assigned
    data[].vehicleReadiness.canRunbooleanWhether the vehicle may be dispatched todaye.g. true
    data[].vehicleReadiness.blockersobject[]
    data[].vehicleReadiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    data[].vehicleReadiness.blockers[].severitystringValues: blockingadvisorye.g. "advisory"
    data[].vehicleReadiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    data[].vehicleReadiness.warningsobject[]
    data[].vehicleReadiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    data[].vehicleReadiness.warnings[].severitystringValues: blockingadvisorye.g. "advisory"
    data[].vehicleReadiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    data[].vehicleReadiness.inspectionRecordedbooleanTrue when the vehicle has a next-inspection date on recorde.g. true
    data[].driverIdnumbernullableID of the driver assigned to this route (driver.id)e.g. 3
    data[].driverNamestringnullableFull name of the assigned drivere.g. "Nguyen Thu Ha"
    data[].backupDriverIdnumbernullableStanding fallback driver (driver.id) covering this route when the regular driver is awaye.g. 9
    data[].backupDriverNamestringnullableFull name of the backup driver
    data[].directionnumbernullable1 outbound (morning pickup), 2 inbound (afternoon drop-off), 3 extra runValues: 123e.g. 1
    data[].colorstringnullableDisplay color (hex)e.g. "#2563eb"
    data[].capacitynumbernullablePassenger capacitye.g. 45
    data[].estimatedTransitTimenumbernullableEstimated transit time, in minutese.g. 35
    data[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].deactivationReasonstringnullableWhy the route was taken out of service
    data[].deactivationEffectiveDatestringnullableDate the withdrawal was intended to take effect. Recorded intent — nothing acts on it yet.e.g. "2026-08-24"
    data[].stopsCountnumberCount of stops on this routee.g. 8
    data[].stopsGeocodednumberStops carrying both lat and lnge.g. 8
    data[].studentsCountnumberRiders with a standing registration on this routee.g. 38
    data[].departureTimestringnullableEarliest planned departure across the route stops, HH:mm:sse.g. "06:35:00"
    data[].pairedRouteIdnumbernullableOpposite-direction sibling — the route sharing this group_ide.g. 12
    data[].pairedRouteCodestringnullableThe paired sibling's code, for the list's link celle.g. "R-101-PM"
    data[].groupIdnumberLinks the legs of one logical service; 0 = ungroupede.g. 4
    data[].totalDistanceKmnumbernullableTotal planned distance, in kilometres (derived; see GetRoute)
    data[].updatedAtstring (date-time)Timestamp of the last edit, used for the review-overdue warning
    data[].readinessobjectThe server's verdict on whether this route generates a usable trip. Never re-derive it client-side.
    data[].readiness.canRunbooleanWhether this route generates a usable tripe.g. false
    data[].readiness.blockersobject[]Every condition that fails; empty when canRun
    data[].readiness.blockers[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    data[].readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    data[].readiness.blockers[].severitystringValues: blockingadvisorye.g. "blocking"
    data[].readiness.blockers[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    data[].readiness.blockers[].missingStopsnumberStops still missing coordinatese.g. 3
    data[].readiness.blockers[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    data[].readiness.blockers[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    data[].readiness.blockers[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    data[].readiness.blockers[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
    data[].readiness.warningsobject[]Conditions that need attention but do not block
    data[].readiness.warnings[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    data[].readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    data[].readiness.warnings[].severitystringValues: blockingadvisorye.g. "blocking"
    data[].readiness.warnings[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    data[].readiness.warnings[].missingStopsnumberStops still missing coordinatese.g. 3
    data[].readiness.warnings[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    data[].readiness.warnings[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    data[].readiness.warnings[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    data[].readiness.warnings[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/routes/{id}

Get a route

Returns the route detail aggregate by primary key.

Parameters

FieldTypeDescription
idpathrequiredintegerNumeric id of the route, as returned in the id field of the list endpoint.

Responses

  • 200Route found
    FieldTypeDescription
    idnumberRoute ID; 0 or omitted on createe.g. 4
    codestringnullableRoute codee.g. "RT-004"
    namestringRoute display namee.g. "Route A - Morning"
    campusIdnumbernullableID of the school (campus) this route servese.g. 12
    campusNamestringnullableName of the campus this route serves; null when unassigned or not joinede.g. "Greenfield High School"
    vehicleIdnumbernullableID of the vehicle assigned to this routee.g. 7
    vehicleNamestringnullableDisplay name of the assigned vehiclee.g. "B-101"
    vehiclePlatestringnullableRegistration plate of the assigned vehiclee.g. "51F-238.45"
    vehicleCapacitynumbernullableSeats on the assigned vehicle (vehicle.capacity); null when no vehicle or not recordede.g. 45
    vehicleReadinessobjectnullableDispatch verdict of the assigned vehicle (detail read only); null when no vehicle is assigned
    vehicleReadiness.canRunbooleanWhether the vehicle may be dispatched todaye.g. true
    vehicleReadiness.blockersobject[]
    vehicleReadiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    vehicleReadiness.blockers[].severitystringValues: blockingadvisorye.g. "advisory"
    vehicleReadiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    vehicleReadiness.warningsobject[]
    vehicleReadiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_DUE_SOON"
    vehicleReadiness.warnings[].severitystringValues: blockingadvisorye.g. "advisory"
    vehicleReadiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. 8
    vehicleReadiness.inspectionRecordedbooleanTrue when the vehicle has a next-inspection date on recorde.g. true
    driverIdnumbernullableID of the driver assigned to this route (driver.id)e.g. 3
    driverNamestringnullableFull name of the assigned drivere.g. "Nguyen Thu Ha"
    backupDriverIdnumbernullableStanding fallback driver (driver.id) covering this route when the regular driver is awaye.g. 9
    backupDriverNamestringnullableFull name of the backup driver
    directionnumbernullable1 outbound (morning pickup), 2 inbound (afternoon drop-off), 3 extra runValues: 123e.g. 1
    colorstringnullableDisplay color (hex)e.g. "#2563eb"
    capacitynumbernullablePassenger capacitye.g. 45
    estimatedTransitTimenumbernullableEstimated transit time, in minutese.g. 35
    statusstringValues: activeinactivedraftarchivede.g. "active"
    deactivationReasonstringnullableWhy the route was taken out of service
    deactivationEffectiveDatestringnullableDate the withdrawal was intended to take effect. Recorded intent — nothing acts on it yet.e.g. "2026-08-24"
    stopsCountnumberCount of stops on this routee.g. 8
    stopsGeocodednumberStops carrying both lat and lnge.g. 8
    studentsCountnumberRiders with a standing registration on this routee.g. 38
    departureTimestringnullableEarliest planned departure across the route stops, HH:mm:sse.g. "06:35:00"
    pairedRouteIdnumbernullableOpposite-direction sibling — the route sharing this group_ide.g. 12
    pairedRouteCodestringnullableThe paired sibling's code, for the list's link celle.g. "R-101-PM"
    groupIdnumberLinks the legs of one logical service; 0 = ungroupede.g. 4
    totalDistanceKmnumbernullableTotal planned distance, in kilometres (derived; see GetRoute)
    updatedAtstring (date-time)Timestamp of the last edit, used for the review-overdue warning
    readinessobjectThe server's verdict on whether this route generates a usable trip. Never re-derive it client-side.
    readiness.canRunbooleanWhether this route generates a usable tripe.g. false
    readiness.blockersobject[]Every condition that fails; empty when canRun
    readiness.blockers[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    readiness.blockers[].severitystringValues: blockingadvisorye.g. "blocking"
    readiness.blockers[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    readiness.blockers[].missingStopsnumberStops still missing coordinatese.g. 3
    readiness.blockers[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    readiness.blockers[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    readiness.blockers[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    readiness.blockers[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
    readiness.warningsobject[]Conditions that need attention but do not block
    readiness.warnings[].codestringStable machine code; the client maps it to routes.readiness.<code>e.g. "NO_DRIVER"
    readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "No default driver assigned"
    readiness.warnings[].severitystringValues: blockingadvisorye.g. "blocking"
    readiness.warnings[].seatsnumberSeats short (OVER_CAPACITY) or seats left (NEAR_CAPACITY)e.g. 2
    readiness.warnings[].missingStopsnumberStops still missing coordinatese.g. 3
    readiness.warnings[].minutesnumberPlanned minutes, for DURATION_OVER_STANDARDe.g. 63
    readiness.warnings[].daysSinceReviewnumberDays since the last edit, for REVIEW_OVERDUEe.g. 82
    readiness.warnings[].arrivalTimestringPlanned arrival at the last school-side stop (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:50"
    readiness.warnings[].bellTimestringCampus first bell (HH:mm), for ARRIVES_AFTER_BELLe.g. "07:30"
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for routes
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Route does not exist
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Stops

GET/v1/stops

List stops (paginated)

Returns a paginated, searchable list of stops, optionally filtered to a geographic bounding box, scoped to the caller when using the Owner permission.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
campusIdqueryinteger
zoneIdqueryinteger
minLatquerynumbermax 90
minLngquerynumbermax 180
maxLatquerynumbermax 90
maxLngquerynumbermax 180

Responses

  • 200Paginated list of stops.
    FieldTypeDescription
    dataobject[]
    data[].idnumberStop ID; only used on update.e.g. 12
    data[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].contactPhonestringnullablee.g. "0901234567"
    data[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].createByUserobjectnullableSummary of the user who created this stop.
    data[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campusobjectCampus reference data.
    data[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.capacitynumbernullable
    data[].campus.studentsCountnumber
    data[].campus.routesCountnumber
    data[].campus.stopsCountnumber
    data[].campus.arrivalTimestringnullable
    data[].campus.departureTimestringnullable
    data[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    data[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    data[].campus.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].campus.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].campusobjectCampus reference data.
    data[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.stops[].campus.capacitynumbernullable
    data[].campus.stops[].campus.studentsCountnumber
    data[].campus.stops[].campus.routesCountnumber
    data[].campus.stops[].campus.stopsCountnumber
    data[].campus.stops[].campus.arrivalTimestringnullable
    data[].campus.stops[].campus.departureTimestringnullable
    data[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campus.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].campus.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].campus.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].campus.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].campus.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].campus.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].campus.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    data[].campus.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].campus.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].campus.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    data[].campus.stops[].campus.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].campus.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].campus.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].campus.stops[].campus.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].campus.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].campus.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].campus.stops[].campusobjectCampus reference data.
    data[].campus.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.stops[].campus.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.stops[].campus.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].campus.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].campus.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.stops[].campus.stops[].campus.capacitynumbernullable
    data[].campus.stops[].campus.stops[].campus.studentsCountnumber
    data[].campus.stops[].campus.stops[].campus.routesCountnumber
    data[].campus.stops[].campus.stops[].campus.stopsCountnumber
    data[].campus.stops[].campus.stops[].campus.arrivalTimestringnullable
    data[].campus.stops[].campus.stops[].campus.departureTimestringnullable
    data[].campus.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].campus.stops[].campus.createByUseranynullableSummary of the user who created this campus
    data[].campus.stops[].campus.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].campus.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].campus.stops[].campus.stops[].zoneobjectZone reference data.
    data[].campus.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].campus.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].campus.stops[].campus.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].campus.stops[].campus.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].campus.stops[].campus.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].campus.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].campus.stops[].campus.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].campus.stops[].campus.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].campus.stops[].campus.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].campus.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].campus.stops[].campus.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].campus.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].campus.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].campus.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].campus.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].campus.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].campus.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].campus.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].campus.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].campus.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].campus.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].campus.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].campus.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].campus.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].campus.stops[].campus.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].campus.stops[].campus.stops[].safety.notestringnullableFree-text note left by the assessor.
    data[].campus.stops[].campus.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].campus.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].campus.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].campus.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].campus.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    data[].campus.stops[].campus.createByUseranynullableSummary of the user who created this campus
    data[].campus.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].campus.stops[].zoneobjectZone reference data.
    data[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].campus.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].campus.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].campus.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].campus.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].campus.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].campus.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].campus.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].campus.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].campus.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].campus.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].campus.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].campus.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].campus.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].campus.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    data[].campus.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].campus.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].campus.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    data[].campus.stops[].zone.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].zone.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].zone.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].campus.stops[].zone.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].campus.stops[].zone.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].campus.stops[].zone.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].campus.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].campus.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].campus.stops[].zone.stops[].campusobjectCampus reference data.
    data[].campus.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].campus.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].campus.stops[].zone.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].campus.stops[].zone.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].campus.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].zone.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].campus.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].campus.stops[].zone.stops[].campus.capacitynumbernullable
    data[].campus.stops[].zone.stops[].campus.studentsCountnumber
    data[].campus.stops[].zone.stops[].campus.routesCountnumber
    data[].campus.stops[].zone.stops[].campus.stopsCountnumber
    data[].campus.stops[].zone.stops[].campus.arrivalTimestringnullable
    data[].campus.stops[].zone.stops[].campus.departureTimestringnullable
    data[].campus.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].campus.stops[].zone.stops[].campus.createByUseranynullableSummary of the user who created this campus
    data[].campus.stops[].zone.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].campus.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].campus.stops[].zone.stops[].zoneobjectZone reference data.
    data[].campus.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].campus.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].campus.stops[].zone.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].campus.stops[].zone.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].campus.stops[].zone.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].campus.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].campus.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].campus.stops[].zone.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].campus.stops[].zone.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].campus.stops[].zone.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].campus.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].campus.stops[].zone.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].campus.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].campus.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].campus.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].campus.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].campus.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].campus.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].campus.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].campus.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].campus.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].campus.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].campus.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].campus.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].campus.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].campus.stops[].zone.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].campus.stops[].zone.stops[].safety.notestringnullableFree-text note left by the assessor.
    data[].campus.stops[].zone.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].campus.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].campus.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].campus.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].campus.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    data[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].campus.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].campus.stops[].safety.notestringnullableFree-text note left by the assessor.
    data[].campus.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    data[].campus.createByUseranynullableSummary of the user who created this campus
    data[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zoneobjectZone reference data.
    data[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    data[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    data[].zone.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].zone.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].campusobjectCampus reference data.
    data[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].zone.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].zone.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].zone.stops[].campus.capacitynumbernullable
    data[].zone.stops[].campus.studentsCountnumber
    data[].zone.stops[].campus.routesCountnumber
    data[].zone.stops[].campus.stopsCountnumber
    data[].zone.stops[].campus.arrivalTimestringnullable
    data[].zone.stops[].campus.departureTimestringnullable
    data[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].zone.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zone.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].zone.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].zone.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].zone.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].zone.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].zone.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    data[].zone.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].zone.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].zone.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    data[].zone.stops[].campus.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].campus.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].campus.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].zone.stops[].campus.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].campus.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].campus.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].campus.stops[].campusobjectCampus reference data.
    data[].zone.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].zone.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].zone.stops[].campus.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].zone.stops[].campus.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].zone.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].campus.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].zone.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].zone.stops[].campus.stops[].campus.capacitynumbernullable
    data[].zone.stops[].campus.stops[].campus.studentsCountnumber
    data[].zone.stops[].campus.stops[].campus.routesCountnumber
    data[].zone.stops[].campus.stops[].campus.stopsCountnumber
    data[].zone.stops[].campus.stops[].campus.arrivalTimestringnullable
    data[].zone.stops[].campus.stops[].campus.departureTimestringnullable
    data[].zone.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].zone.stops[].campus.stops[].campus.createByUseranynullableSummary of the user who created this campus
    data[].zone.stops[].campus.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].zone.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].zone.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zone.stops[].campus.stops[].zoneobjectZone reference data.
    data[].zone.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.stops[].campus.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.stops[].campus.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.stops[].campus.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.stops[].campus.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.stops[].campus.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].zone.stops[].campus.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].zone.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.stops[].campus.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].zone.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].zone.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].zone.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].zone.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].zone.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].zone.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].zone.stops[].campus.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].zone.stops[].campus.stops[].safety.notestringnullableFree-text note left by the assessor.
    data[].zone.stops[].campus.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].zone.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].zone.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].zone.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].zone.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    data[].zone.stops[].campus.createByUseranynullableSummary of the user who created this campus
    data[].zone.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zone.stops[].zoneobjectZone reference data.
    data[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].zone.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    data[].zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    data[].zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    data[].zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    data[].zone.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    data[].zone.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    data[].zone.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    data[].zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    data[].zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    data[].zone.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    data[].zone.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    data[].zone.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    data[].zone.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    data[].zone.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    data[].zone.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    data[].zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    data[].zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    data[].zone.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    data[].zone.stops[].zone.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].zone.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].zone.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    data[].zone.stops[].zone.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    data[].zone.stops[].zone.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    data[].zone.stops[].zone.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    data[].zone.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    data[].zone.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    data[].zone.stops[].zone.stops[].campusobjectCampus reference data.
    data[].zone.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    data[].zone.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    data[].zone.stops[].zone.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    data[].zone.stops[].zone.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    data[].zone.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].zone.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    data[].zone.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    data[].zone.stops[].zone.stops[].campus.capacitynumbernullable
    data[].zone.stops[].zone.stops[].campus.studentsCountnumber
    data[].zone.stops[].zone.stops[].campus.routesCountnumber
    data[].zone.stops[].zone.stops[].campus.stopsCountnumber
    data[].zone.stops[].zone.stops[].campus.arrivalTimestringnullable
    data[].zone.stops[].zone.stops[].campus.departureTimestringnullable
    data[].zone.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    data[].zone.stops[].zone.stops[].campus.createByUseranynullableSummary of the user who created this campus
    data[].zone.stops[].zone.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    data[].zone.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    data[].zone.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    data[].zone.stops[].zone.stops[].zoneobjectZone reference data.
    data[].zone.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    data[].zone.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    data[].zone.stops[].zone.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    data[].zone.stops[].zone.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    data[].zone.stops[].zone.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    data[].zone.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    data[].zone.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    data[].zone.stops[].zone.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    data[].zone.stops[].zone.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    data[].zone.stops[].zone.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    data[].zone.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    data[].zone.stops[].zone.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    data[].zone.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    data[].zone.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    data[].zone.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    data[].zone.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    data[].zone.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    data[].zone.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    data[].zone.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    data[].zone.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    data[].zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].zone.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].zone.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].zone.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].zone.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].zone.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].zone.stops[].zone.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].zone.stops[].zone.stops[].safety.notestringnullableFree-text note left by the assessor.
    data[].zone.stops[].zone.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].zone.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].zone.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].zone.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].zone.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    data[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].zone.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].zone.stops[].safety.notestringnullableFree-text note left by the assessor.
    data[].zone.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    data[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    data[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    data[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    data[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    data[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    data[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    data[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    data[].safety.notestringnullableFree-text note left by the assessor.
    data[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    data[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    data[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    data[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    data[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    data[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    data[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    data[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    data[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    data[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    data[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/stops/{id}

Get a stop by ID

Returns a single stop with its related entities.

Parameters

FieldTypeDescription
idpathrequiredintegerNumeric id of the stop, as returned in the id field of the list endpoint.

Responses

  • 200Stop found.
    FieldTypeDescription
    idnumberStop ID; only used on update.e.g. 12
    namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    latnumberLatitude coordinate of the stop.e.g. 10.7626
    lngnumberLongitude coordinate of the stop.e.g. 106.6602
    codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    contactPhonestringnullablee.g. "0901234567"
    statusstringValues: activeinactivedraftarchivede.g. "active"
    activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    createByUserobjectnullableSummary of the user who created this stop.
    createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    updateByUserobjectnullableSummary of the user who last updated this stop.
    updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campusobjectCampus reference data.
    campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.lifecycleStatusstringValues: activeinactivepaused
    campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.capacitynumbernullable
    campus.studentsCountnumber
    campus.routesCountnumber
    campus.stopsCountnumber
    campus.arrivalTimestringnullable
    campus.departureTimestringnullable
    campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campusobjectCampus reference data.
    campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.stops[].campus.capacitynumbernullable
    campus.stops[].campus.studentsCountnumber
    campus.stops[].campus.routesCountnumber
    campus.stops[].campus.stopsCountnumber
    campus.stops[].campus.arrivalTimestringnullable
    campus.stops[].campus.departureTimestringnullable
    campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].campus.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].campus.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].campus.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].campus.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].campus.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].campus.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].campusobjectCampus reference data.
    campus.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.stops[].campus.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    campus.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].campus.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    campus.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.stops[].campus.stops[].campus.capacitynumbernullable
    campus.stops[].campus.stops[].campus.studentsCountnumber
    campus.stops[].campus.stops[].campus.routesCountnumber
    campus.stops[].campus.stops[].campus.stopsCountnumber
    campus.stops[].campus.stops[].campus.arrivalTimestringnullable
    campus.stops[].campus.stops[].campus.departureTimestringnullable
    campus.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campus.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].campus.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].campus.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].campus.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].campus.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].campus.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].campus.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].campus.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].campus.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].campus.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].campus.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].campus.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].campus.stops[].campusobjectCampus reference data.
    campus.stops[].campus.stops[].campus.stops[].zoneobjectZone reference data.
    campus.stops[].campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].campus.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].campus.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].campus.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].campus.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.stops[].campus.stops[].campus.createByUseranynullableSummary of the user who created this campus
    campus.stops[].campus.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    campus.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    campus.stops[].campus.stops[].zoneobjectZone reference data.
    campus.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    campus.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    campus.stops[].campus.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    campus.stops[].campus.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    campus.stops[].campus.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    campus.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    campus.stops[].campus.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    campus.stops[].campus.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    campus.stops[].campus.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    campus.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    campus.stops[].campus.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    campus.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    campus.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    campus.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    campus.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    campus.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    campus.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    campus.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    campus.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    campus.stops[].campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].campus.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].campus.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].campus.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].campus.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].campus.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].campus.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].campus.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].campus.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].campus.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].campus.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].campus.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].campus.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].campus.stops[].zone.stops[].campusobjectCampus reference data.
    campus.stops[].campus.stops[].zone.stops[].zoneobjectZone reference data.
    campus.stops[].campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].campus.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].campus.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].campus.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].campus.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    campus.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    campus.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    campus.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    campus.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    campus.stops[].campus.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    campus.stops[].campus.stops[].safety.notestringnullableFree-text note left by the assessor.
    campus.stops[].campus.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    campus.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.stops[].campus.createByUseranynullableSummary of the user who created this campus
    campus.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    campus.stops[].zoneobjectZone reference data.
    campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    campus.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    campus.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    campus.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    campus.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    campus.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    campus.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    campus.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].zone.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].zone.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].zone.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].zone.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    campus.stops[].zone.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    campus.stops[].zone.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    campus.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    campus.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].campusobjectCampus reference data.
    campus.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    campus.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    campus.stops[].zone.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    campus.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].zone.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    campus.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    campus.stops[].zone.stops[].campus.capacitynumbernullable
    campus.stops[].zone.stops[].campus.studentsCountnumber
    campus.stops[].zone.stops[].campus.routesCountnumber
    campus.stops[].zone.stops[].campus.stopsCountnumber
    campus.stops[].zone.stops[].campus.arrivalTimestringnullable
    campus.stops[].zone.stops[].campus.departureTimestringnullable
    campus.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    campus.stops[].zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].zone.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zone.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].zone.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].zone.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].zone.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].zone.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].zone.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].zone.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].zone.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].zone.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].zone.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].zone.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].campus.stops[].campusobjectCampus reference data.
    campus.stops[].zone.stops[].campus.stops[].zoneobjectZone reference data.
    campus.stops[].zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].zone.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].zone.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].zone.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].zone.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.stops[].zone.stops[].campus.createByUseranynullableSummary of the user who created this campus
    campus.stops[].zone.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    campus.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    campus.stops[].zone.stops[].zoneobjectZone reference data.
    campus.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    campus.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    campus.stops[].zone.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    campus.stops[].zone.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    campus.stops[].zone.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    campus.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    campus.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    campus.stops[].zone.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    campus.stops[].zone.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    campus.stops[].zone.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    campus.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    campus.stops[].zone.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    campus.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    campus.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    campus.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    campus.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    campus.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    campus.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    campus.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    campus.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    campus.stops[].zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    campus.stops[].zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    campus.stops[].zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    campus.stops[].zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    campus.stops[].zone.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    campus.stops[].zone.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    campus.stops[].zone.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    campus.stops[].zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    campus.stops[].zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    campus.stops[].zone.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    campus.stops[].zone.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    campus.stops[].zone.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    campus.stops[].zone.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    campus.stops[].zone.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    campus.stops[].zone.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    campus.stops[].zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    campus.stops[].zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    campus.stops[].zone.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    campus.stops[].zone.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    campus.stops[].zone.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    campus.stops[].zone.stops[].zone.stops[].campusobjectCampus reference data.
    campus.stops[].zone.stops[].zone.stops[].zoneobjectZone reference data.
    campus.stops[].zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].zone.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].zone.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].zone.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].zone.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    campus.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    campus.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    campus.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    campus.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    campus.stops[].zone.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    campus.stops[].zone.stops[].safety.notestringnullableFree-text note left by the assessor.
    campus.stops[].zone.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    campus.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    campus.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    campus.stops[].safety.notestringnullableFree-text note left by the assessor.
    campus.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    campus.createByUseranynullableSummary of the user who created this campus
    campus.updateByUseranynullableSummary of the user who last updated this campus
    campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zoneobjectZone reference data.
    zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.codestringnullableShort unique zone codee.g. "Z-001"
    zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campusobjectCampus reference data.
    zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    zone.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    zone.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    zone.stops[].campus.capacitynumbernullable
    zone.stops[].campus.studentsCountnumber
    zone.stops[].campus.routesCountnumber
    zone.stops[].campus.stopsCountnumber
    zone.stops[].campus.arrivalTimestringnullable
    zone.stops[].campus.departureTimestringnullable
    zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].campus.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].campus.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].campus.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].campus.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].campus.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].campus.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].campus.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].campus.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].campusobjectCampus reference data.
    zone.stops[].campus.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    zone.stops[].campus.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    zone.stops[].campus.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    zone.stops[].campus.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].campus.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    zone.stops[].campus.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    zone.stops[].campus.stops[].campus.capacitynumbernullable
    zone.stops[].campus.stops[].campus.studentsCountnumber
    zone.stops[].campus.stops[].campus.routesCountnumber
    zone.stops[].campus.stops[].campus.stopsCountnumber
    zone.stops[].campus.stops[].campus.arrivalTimestringnullable
    zone.stops[].campus.stops[].campus.departureTimestringnullable
    zone.stops[].campus.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    zone.stops[].campus.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].campus.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].campus.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campus.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].campus.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].campus.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].campus.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].campus.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].campus.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].campus.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].campus.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].campus.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].campus.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].campus.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].campus.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].campus.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].campus.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].campus.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].campus.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].campus.stops[].campusobjectCampus reference data.
    zone.stops[].campus.stops[].campus.stops[].zoneobjectZone reference data.
    zone.stops[].campus.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].campus.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].campus.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].campus.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].campus.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].campus.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].campus.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].campus.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].campus.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].campus.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].campus.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    zone.stops[].campus.stops[].campus.createByUseranynullableSummary of the user who created this campus
    zone.stops[].campus.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    zone.stops[].campus.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    zone.stops[].campus.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zone.stops[].campus.stops[].zoneobjectZone reference data.
    zone.stops[].campus.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.stops[].campus.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.stops[].campus.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.stops[].campus.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    zone.stops[].campus.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    zone.stops[].campus.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].campus.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.stops[].campus.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.stops[].campus.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    zone.stops[].campus.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    zone.stops[].campus.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.stops[].campus.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    zone.stops[].campus.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.stops[].campus.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.stops[].campus.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stops[].campus.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.stops[].campus.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.stops[].campus.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.stops[].campus.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stops[].campus.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].campus.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].campus.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].campus.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].campus.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].campus.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].campus.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].campus.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].campus.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].campus.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].campus.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].campus.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].campus.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].campus.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].campus.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].campus.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].campus.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].campus.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].campus.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].campus.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].campus.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].campus.stops[].zone.stops[].campusobjectCampus reference data.
    zone.stops[].campus.stops[].zone.stops[].zoneobjectZone reference data.
    zone.stops[].campus.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].campus.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].campus.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].campus.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].campus.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].campus.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].campus.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].campus.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].campus.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].campus.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].campus.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].campus.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    zone.stops[].campus.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    zone.stops[].campus.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    zone.stops[].campus.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    zone.stops[].campus.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    zone.stops[].campus.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    zone.stops[].campus.stops[].safety.notestringnullableFree-text note left by the assessor.
    zone.stops[].campus.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    zone.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    zone.stops[].campus.createByUseranynullableSummary of the user who created this campus
    zone.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zone.stops[].zoneobjectZone reference data.
    zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    zone.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    zone.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].zone.stops[].createByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].zone.stops[].createByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].zone.stops[].createByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].zone.stops[].createByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].zone.stops[].updateByUser.idintegernullableUser id. null when the user is platform support and the caller may not see staff.e.g. 12
    zone.stops[].zone.stops[].updateByUser.namestringnullableComputed display name (first + last name). null when the user is platform support and the caller may not see staff.e.g. "Nguyen Van A"
    zone.stops[].zone.stops[].updateByUser.avatarstringnullableAvatar URL or file reference.e.g. "avatars/user-12.png"
    zone.stops[].zone.stops[].updateByUser.isPlatformSupportbooleanTrue when the user is Stracker platform staff (SuperAdmin / Agent), whoever is reading. The client shows its localised "Stracker support" label; identity fields are null unless the caller holds platform:staff:view.e.g. false
    zone.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].campusobjectCampus reference data.
    zone.stops[].zone.stops[].campus.idnumberCampus ID; 0 or omitted on createe.g. 12
    zone.stops[].zone.stops[].campus.namestringCampus display namemin length 3 · e.g. "Co so Quan 1"
    zone.stops[].zone.stops[].campus.addressstringnullableStreet address of the campuse.g. "123 Nguyen Van Cu, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].campus.phonestringnullableVietnamese-format contact phone numbere.g. "0912345678"
    zone.stops[].zone.stops[].campus.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].zone.stops[].campus.lifecycleStatusstringValues: activeinactivepaused
    zone.stops[].zone.stops[].campus.codestringStable per-tenant campus codee.g. "BT-TH-01"
    zone.stops[].zone.stops[].campus.capacitynumbernullable
    zone.stops[].zone.stops[].campus.studentsCountnumber
    zone.stops[].zone.stops[].campus.routesCountnumber
    zone.stops[].zone.stops[].campus.stopsCountnumber
    zone.stops[].zone.stops[].campus.arrivalTimestringnullable
    zone.stops[].zone.stops[].campus.departureTimestringnullable
    zone.stops[].zone.stops[].campus.stopsobject[]Stops associated with this campus; populated only when requested with the stops relation
    zone.stops[].zone.stops[].campus.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].zone.stops[].campus.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].zone.stops[].campus.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].campus.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].zone.stops[].campus.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zone.stops[].campus.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].zone.stops[].campus.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].zone.stops[].campus.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].zone.stops[].campus.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].zone.stops[].campus.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].zone.stops[].campus.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].zone.stops[].campus.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].zone.stops[].campus.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].zone.stops[].campus.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].zone.stops[].campus.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].zone.stops[].campus.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].zone.stops[].campus.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].zone.stops[].campus.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].zone.stops[].campus.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].zone.stops[].campus.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].campus.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].campus.stops[].campusobjectCampus reference data.
    zone.stops[].zone.stops[].campus.stops[].zoneobjectZone reference data.
    zone.stops[].zone.stops[].campus.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].zone.stops[].campus.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].zone.stops[].campus.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].zone.stops[].campus.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].zone.stops[].campus.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].zone.stops[].campus.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].zone.stops[].campus.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].zone.stops[].campus.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].zone.stops[].campus.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].zone.stops[].campus.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].zone.stops[].campus.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    zone.stops[].zone.stops[].campus.createByUseranynullableSummary of the user who created this campus
    zone.stops[].zone.stops[].campus.updateByUseranynullableSummary of the user who last updated this campus
    zone.stops[].zone.stops[].campus.createdAtstring (date-time)Creation timestampe.g. "2026-06-01T08:30:00.000Z"
    zone.stops[].zone.stops[].campus.updatedAtstring (date-time)Last update timestampe.g. "2026-06-15T10:12:00.000Z"
    zone.stops[].zone.stops[].zoneobjectZone reference data.
    zone.stops[].zone.stops[].zone.idnumberZone ID; 0 or omitted on createe.g. 7
    zone.stops[].zone.stops[].zone.namestringZone display namemin length 3 · e.g. "Khu vuc Quan 7"
    zone.stops[].zone.stops[].zone.descriptionstringnullableFree-text description of the zonee.g. "Bao gom cac tuyen duong quanh Phu My Hung"
    zone.stops[].zone.stops[].zone.textColorstringnullableHex text color used for the zone badgee.g. "#FFFFFF"
    zone.stops[].zone.stops[].zone.bgColorstringnullableHex background color used for the zone badgee.g. "#1E90FF"
    zone.stops[].zone.stops[].zone.statusbooleanActive status; true = active, false = inactivee.g. true
    zone.stops[].zone.stops[].zone.accentColorstringIdentifying colour for the zone, e.g. #2563eb.e.g. "#2563eb"
    zone.stops[].zone.stops[].zone.boundaryobjectnullableZone boundary as a GeoJSON Polygon ([lng, lat]), or null when none is drawn.
    zone.stops[].zone.stops[].zone.centroidLatnumbernullableCentroid latitude of the boundarye.g. 10.785
    zone.stops[].zone.stops[].zone.centroidLngnumbernullableCentroid longitude of the boundarye.g. 106.705
    zone.stops[].zone.stops[].zone.isDraftbooleanTrue while the zone is still a draft; gates the Publish action in the design.e.g. false
    zone.stops[].zone.stops[].zone.codestringnullableShort unique zone codee.g. "Z-001"
    zone.stops[].zone.stops[].zone.capacityintegerRecommended passenger capacity for this zonee.g. 250
    zone.stops[].zone.stops[].zone.coverageAreaSqkmnumberCovered area in square kilometrese.g. 12.4
    zone.stops[].zone.stops[].zone.schoolsCountnumberCached count of schools covered by this zonee.g. 3
    zone.stops[].zone.stops[].zone.stopsCountnumberCached count of stops in this zonee.g. 14
    zone.stops[].zone.stops[].zone.studentsCountnumberCached count of students served by this zonee.g. 210
    zone.stops[].zone.stops[].zone.routesCountnumberCached count of routes touching this zonee.g. 5
    zone.stops[].zone.stops[].zone.blockedStopsCountnumberStops in this zone that cannot currently be used (draft, no coordinates, unsurveyed or risky, over capacity, or riders with no route).e.g. 2
    zone.stops[].zone.stops[].zone.stopsobject[]Stops associated with this zone; populated only when requested with the stops relation
    zone.stops[].zone.stops[].zone.stops[].idnumberStop ID; only used on update.e.g. 12
    zone.stops[].zone.stops[].zone.stops[].namestringShort display name for the stop.max length 5 · e.g. "Cong A"
    zone.stops[].zone.stops[].zone.stops[].addressstringFull street address of the stop.max length 255 · e.g. "123 Nguyen Trai, Phuong 4, Quan 5, TP.HCM"
    zone.stops[].zone.stops[].zone.stops[].fullAddressstringNormalized full address, typically resolved from a geocoding lookup.e.g. "123 Nguyen Trai, Phuong 4, Quan 5, Thanh pho Ho Chi Minh, Vietnam"
    zone.stops[].zone.stops[].zone.stops[].campusIdnumbernullableID of the campus this stop serves; null when it serves none.e.g. 3
    zone.stops[].zone.stops[].zone.stops[].zoneIdnumbernullableID of the zone this stop belongs to; null when it is in none.e.g. 5
    zone.stops[].zone.stops[].zone.stops[].stopTypenumbernullableLive type column; plain smallint, no documented enum value-set.e.g. 1
    zone.stops[].zone.stops[].zone.stops[].latnumberLatitude coordinate of the stop.e.g. 10.7626
    zone.stops[].zone.stops[].zone.stops[].lngnumberLongitude coordinate of the stop.e.g. 106.6602
    zone.stops[].zone.stops[].zone.stops[].codestringnullableDisplay code, e.g. STP-001. Unique among live stops via uq_stop_code.e.g. "STP-001"
    zone.stops[].zone.stops[].zone.stops[].walkRadiusMnumbernullableExpected walking distance to this stop, in metres. The Stops screen warns past 600.e.g. 450
    zone.stops[].zone.stops[].zone.stops[].contactNamestringnullableWho the driver calls at this stop by default (a trip can override it)e.g. "Bác bảo vệ cổng A"
    zone.stops[].zone.stops[].zone.stops[].contactPhonestringnullablee.g. "0901234567"
    zone.stops[].zone.stops[].zone.stops[].statusstringValues: activeinactivedraftarchivede.g. "active"
    zone.stops[].zone.stops[].zone.stops[].activeInSmartRoutebooleannullableWhether this stop is eligible for smart-route auto-assignment.e.g. true
    zone.stops[].zone.stops[].zone.stops[].geofenceCoordinatesany[]Polygon vertices defining the geofence boundary around the stop.
    zone.stops[].zone.stops[].zone.stops[].geofenceStatusbooleanWhether geofence-based check-in/out is active for this stop.e.g. true
    zone.stops[].zone.stops[].zone.stops[].createByUserobjectnullableSummary of the user who created this stop.
    zone.stops[].zone.stops[].zone.stops[].updateByUserobjectnullableSummary of the user who last updated this stop.
    zone.stops[].zone.stops[].zone.stops[].createdAtstringnullableCreation timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].zone.stops[].updatedAtstringnullableLast-update timestamp, formatted.e.g. "04/07/2026 10:15:00"
    zone.stops[].zone.stops[].zone.stops[].campusobjectCampus reference data.
    zone.stops[].zone.stops[].zone.stops[].zoneobjectZone reference data.
    zone.stops[].zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].zone.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].zone.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].zone.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].zone.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    zone.stops[].zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    zone.stops[].zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    zone.stops[].zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    zone.stops[].zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    zone.stops[].zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    zone.stops[].zone.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    zone.stops[].zone.stops[].safety.notestringnullableFree-text note left by the assessor.
    zone.stops[].zone.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    zone.stops[].zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    zone.stops[].safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    zone.stops[].safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    zone.stops[].safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    zone.stops[].safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    zone.stops[].safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    zone.stops[].safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    zone.stops[].safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    zone.stops[].safety.notestringnullableFree-text note left by the assessor.
    zone.stops[].safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    zone.stops[].capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    zone.stops[].capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    zone.stops[].routesCountnumberNumber of routes that serve this stop.e.g. 2
    zone.stops[].routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    zone.stops[].routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    zone.stops[].soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    zone.stops[].soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    zone.stops[].ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    zone.stops[].blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    zone.stops[].publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
    safetyobjectLatest safety survey for this stop; omitted when the stop has never been surveyed.
    safety.scorenumberSafety score 0-5, as recorded by the assessor.e.g. 4
    safety.hasCrossingbooleanMarked pedestrian crossing within sight of the stop.e.g. true
    safety.hasLightingbooleanStreet lighting covers the waiting area.e.g. true
    safety.hasCurbbooleanRaised curb separating the waiting area from traffic.e.g. true
    safety.hasShelterbooleanWeather shelter at the waiting area.e.g. false
    safety.surveyedAtstringnullableWhen this assessment was made, formatted.e.g. "14/08/2026 09:20:00"
    safety.notestringnullableFree-text note left by the assessor.
    safety.surveyedByNamestringnullableDisplay name of the assessor, when the caller resolved it.
    capacityRecommendednumbernullablePlanned rider count for the stop.e.g. 14
    capacityMaxnumbernullableMaximum riders the stop can hold.e.g. 16
    routesCountnumberNumber of routes that serve this stop.e.g. 2
    routeLabelsstring[]Code, or name when there is no code, of each live route calling at the stop; sorted.
    routeNamesstring[]NAME of each live route calling at the stop; sorted. Sibling of routeLabels, which prefers the code — a caller that shows routes to a reader wants these.
    soleRouteDirectionnumbernullableService window code of the ONLY route calling here; null when the stop is served by none or by several (a hub has no single window).e.g. 1
    soleRoutePickupEtastringnullableScheduled arrival, on the same one-route-only condition as soleRouteDirection.e.g. "06:42"
    ridersCountnumberNumber of riders assigned to this stop.e.g. 14
    blockReasonsstring[]Reasons the stop cannot currently be used, most severe first; empty when usable.Values: draftnoCoordsunsurveyedriskoverCapacityridersNoRoute
    publishBlockersstring[]Publish checks the stop fails, in checklist order; empty when it may be published.Values: coordssafetyaddresszone
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Stop.Read permission.
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Stop does not exist.
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Trips

GET/v1/trips

List trips

Returns a paginated, searchable list of trips, filterable by status, route, or date.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
statusquerystringValues: scheduledin_progresscompletedcancelled
routeIdqueryinteger
legLabelquerystring | string[]
campusIdquerystring | string[]
driverIdqueryinteger
vehicleIdqueryinteger
unassignedqueryboolean
providerRunqueryboolean
attentionquerystringValues: blockedlateupcoming_unready
datequerystring
dateFromquerystring
dateToquerystring

Responses

  • 200Paginated list of trips
    FieldTypeDescription
    dataobject[]
    data[].idnumberTrip ID; 0 or omitted on createe.g. 91
    data[].codestringnullableTrip codee.g. "TR-2026-0630-004"
    data[].routeIdnumberID of the route this trip executese.g. 4
    data[].datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    data[].driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    data[].vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    data[].statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    data[].plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    data[].plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    data[].passengersCountnumberCount of passengers assigned to this tripe.g. 22
    data[].legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    data[].cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    data[].cancelNotestringnullableNote sent with the cancellation
    data[].rescheduleReasonstringnullableWhy the departure was last moved
    data[].originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    data[].revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    data[].needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    data[].reassignmentFlagsobject[]Open reassignment flags of the trip
    data[].reassignmentFlags[].idstring
    data[].reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    data[].reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    data[].reassignmentFlags[].resourceIdnumber
    data[].reassignmentFlags[].unavailabilityIdnumber
    data[].reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    data[].reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    data[].reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    data[].reassignmentFlags[].flaggedAtstringISO instant
    data[].reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    data[].reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    data[].reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    data[].availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    data[].availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    data[].availabilityWarnings[].tripIdstring
    data[].availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    data[].availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    data[].availabilityWarnings[].resourceIdnumber
    data[].availabilityWarnings[].unavailabilityIdnumber
    data[].availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    data[].availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    data[].availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
    data[].routeobjectnullable
    data[].route.idnumbere.g. 12
    data[].route.namestringe.g. "Tuyến 12"
    data[].route.codestringnullablee.g. "R-12"
    data[].siteobjectnullableThe route's campus; null when unlinked
    data[].site.idnumbere.g. 3
    data[].site.namestringe.g. "THCS Washington"
    data[].directionstringnullableValues: outboundinboundextra
    data[].driverobjectnullableNull = unassigned, which is a block
    data[].driver.idnumbere.g. 4
    data[].driver.namestringDisplay name from the linked persone.g. "Trần Minh Khoa"
    data[].vehicleobjectnullableNull = unassigned, which is a block
    data[].vehicle.idnumbere.g. 7
    data[].vehicle.numberstringnullableFleet numbere.g. "B-102"
    data[].vehicle.regoNumberstringnullablePlatee.g. "51F-114.09"
    data[].vehicle.capacitynumbernullablee.g. 29
    data[].scheduleobject
    data[].schedule.plannedStartTimestringnullablee.g. "07:10:00"
    data[].schedule.plannedEndTimestringnullablee.g. "07:55:00"
    data[].schedule.actualStartTimestringnullableActual departure on the tenant's wall clock, read from trip.actual_start_at (stamped when the driver starts the trip); null until it startse.g. "07:24:00"
    data[].schedule.actualEndTimestringnullableWhen the trip actually finished on the tenant's wall clock, read from trip.actual_end_at (stamped when the driver completes the trip); null until it does. The drawer's log tab needs it to close the trip's story — without it, a completed trip's history stopped at departure.e.g. "07:55:00"
    data[].schedule.delayMinutesnumbernullableMinutes behind plan; null when never measurede.g. 14
    data[].schedule.estimatedTransitTimenumbernullablePlanned duration in minutese.g. 45
    data[].progressobject
    data[].progress.stopsCompletednumbere.g. 4
    data[].progress.stopsTotalnumbere.g. 10
    data[].progress.percentnumbernullableRounded percentage; null when the trip has no stops, so the client shows "—" not 0%e.g. 40
    data[].passengersobject
    data[].passengers.assignednumberManifest size, excluding cancelled assignmentse.g. 10
    data[].passengers.boardednumberAboard right now — alighted passengers are not countede.g. 4
    data[].passengers.alightednumbere.g. 0
    data[].passengers.absentnumbere.g. 1
    data[].passengers.capacitynumbernullableSeats, from the trip override or the vehiclee.g. 29
    data[].blockedbooleanServer verdict: this trip will not leave as schedulede.g. true
    data[].blockReasonsstring[]Empty when not blocked. Codes, not prose — the client owns the wordingValues: no_driverno_vehicle
    data[].latebooleanTrue when the trip is in progress or scheduled (a driver can report late before departing) and at least 10 minutes behind plane.g. false
    data[].creationSourcestringValues: generatedadhocimportede.g. "generated"
    data[].createdAtstringnullableWhen the trip row was created. Pairs with creationSource to give the drawer log its first entry — the moment the trip came into existence, which no audit row records because generation is a write by the system rather than by a user.e.g. "2026-08-30T05:00:00.000Z"
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for trips
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips

Create trip

Creates a new trip (a dated execution of a route). Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Parameters

FieldTypeDescription
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
idintegerdefault 0
codestringnullablemax length 40
routeIdrequirednumber
daterequiredstringmin length 1
driverIdnumbernullable
vehicleIdnumbernullable
legLabelstringnullablemax length 60
statusstringValues: scheduledin_progresscompletedcancelled
plannedStartTimestringnullable
plannedEndTimestringnullable

Responses

  • 201Trip created
    FieldTypeDescription
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringnullableTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringnullableNote sent with the cancellation
    rescheduleReasonstringnullableWhy the departure was last moved
    originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Example
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write permission for trips
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 409A trip with the same route/date/schedule combination already exists

    A new trip starts scheduled; any other status is refused. params: tripId, currentStatus, attempted

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Example
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/trips/{id}

Get a trip

Returns the trip by primary key as the enriched board row: labels, stop progress, manifest counts and the readiness verdict, plus every TripDto field.

Parameters

FieldTypeDescription
idpathrequiredintegerNumeric id of the trip, as returned in the id field of the list endpoint.

Responses

  • 200Trip found
    FieldTypeDescription
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringnullableTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringnullableNote sent with the cancellation
    rescheduleReasonstringnullableWhy the departure was last moved
    originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
    routeobjectnullable
    route.idnumbere.g. 12
    route.namestringe.g. "Tuyến 12"
    route.codestringnullablee.g. "R-12"
    siteobjectnullableThe route's campus; null when unlinked
    site.idnumbere.g. 3
    site.namestringe.g. "THCS Washington"
    directionstringnullableValues: outboundinboundextra
    driverobjectnullableNull = unassigned, which is a block
    driver.idnumbere.g. 4
    driver.namestringDisplay name from the linked persone.g. "Trần Minh Khoa"
    vehicleobjectnullableNull = unassigned, which is a block
    vehicle.idnumbere.g. 7
    vehicle.numberstringnullableFleet numbere.g. "B-102"
    vehicle.regoNumberstringnullablePlatee.g. "51F-114.09"
    vehicle.capacitynumbernullablee.g. 29
    scheduleobject
    schedule.plannedStartTimestringnullablee.g. "07:10:00"
    schedule.plannedEndTimestringnullablee.g. "07:55:00"
    schedule.actualStartTimestringnullableActual departure on the tenant's wall clock, read from trip.actual_start_at (stamped when the driver starts the trip); null until it startse.g. "07:24:00"
    schedule.actualEndTimestringnullableWhen the trip actually finished on the tenant's wall clock, read from trip.actual_end_at (stamped when the driver completes the trip); null until it does. The drawer's log tab needs it to close the trip's story — without it, a completed trip's history stopped at departure.e.g. "07:55:00"
    schedule.delayMinutesnumbernullableMinutes behind plan; null when never measurede.g. 14
    schedule.estimatedTransitTimenumbernullablePlanned duration in minutese.g. 45
    progressobject
    progress.stopsCompletednumbere.g. 4
    progress.stopsTotalnumbere.g. 10
    progress.percentnumbernullableRounded percentage; null when the trip has no stops, so the client shows "—" not 0%e.g. 40
    passengersobject
    passengers.assignednumberManifest size, excluding cancelled assignmentse.g. 10
    passengers.boardednumberAboard right now — alighted passengers are not countede.g. 4
    passengers.alightednumbere.g. 0
    passengers.absentnumbere.g. 1
    passengers.capacitynumbernullableSeats, from the trip override or the vehiclee.g. 29
    blockedbooleanServer verdict: this trip will not leave as schedulede.g. true
    blockReasonsstring[]Empty when not blocked. Codes, not prose — the client owns the wordingValues: no_driverno_vehicle
    latebooleanTrue when the trip is in progress or scheduled (a driver can report late before departing) and at least 10 minutes behind plane.g. false
    creationSourcestringValues: generatedadhocimportede.g. "generated"
    createdAtstringnullableWhen the trip row was created. Pairs with creationSource to give the drawer log its first entry — the moment the trip came into existence, which no audit row records because generation is a write by the system rather than by a user.e.g. "2026-08-30T05:00:00.000Z"
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for trips
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Example
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

PATCH/v1/trips/{id}

Update trip

Updates an existing trip identified by the path ID. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
idintegerdefault 0
codestringnullablemax length 40
routeIdrequirednumber
daterequiredstringmin length 1
driverIdnumbernullable
vehicleIdnumbernullable
legLabelstringnullablemax length 60
statusstringValues: scheduledin_progresscompletedcancelled
plannedStartTimestringnullable
plannedEndTimestringnullable
expectedRevinteger

Responses

  • 200Trip updated
    FieldTypeDescription
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringnullableTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringnullableNote sent with the cancellation
    rescheduleReasonstringnullableWhy the departure was last moved
    originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Example
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Example
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409expectedRev differs from the trip rev; nothing was written. params: tripId, expectedRev, actualRev, changedFields, changedBy, changedAt

    status differs from the trip status: the lifecycle moves only through assign, cancel, delete and the driver start / complete. params: tripId, currentStatus, attempted

    A linked provider runs the trip; recall its assignment before crewing it with the school

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Example
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips/{id}/assign

Assign or clear a trip’s driver and vehicle

Omit a field to leave it unchanged; send explicit null to unassign. A driver who cannot drive is rejected by the fleet-wide gate; one already committed to an overlapping trip that day is a 409 unless allowDoubleBooking is set, which is recorded in the audit log. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
driverIdintegernullable
vehicleIdintegernullable
allowDoubleBookingbooleandefault false
expectedRevinteger

Responses

  • 201Assignment saved
    FieldTypeDescription
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringnullableTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringnullableNote sent with the cancellation
    rescheduleReasonstringnullableWhy the departure was last moved
    originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Example
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Example
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Driver already has an overlapping trip that day

    The driver or vehicle is on an overlapping assigned charter booking (not overridable)

    Trip is cancelled or completed — assigning crew would commit them to a run that will not happen

    A linked provider runs the trip; recall its assignment before crewing it with the school

    expectedRev is older than the trip: nothing was written; params name the changed fields, who changed them and when

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Example
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips/{id}/cancel

Cancel a trip

Cancels the trip and records why. The reason is required — it selects the guardian notification and is the trip log’s only account of the decision afterwards. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
reasonrequiredstringmin length 1 · max length 160
notestringmax length 500
expectedRevinteger

Responses

  • 201Trip cancelled
    FieldTypeDescription
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringnullableTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringnullableNote sent with the cancellation
    rescheduleReasonstringnullableWhy the departure was last moved
    originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Example
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Example
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Trip is already cancelled, or has already completed

    expectedRev is older than the trip: nothing was written; params name the changed fields, who changed them and when

    Example
    {
      "type": "https://stracker.io/errors/stale-trip",
      "title": "Stale trip",
      "status": 409,
      "detail": "Stale trip",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "STALE_TRIP"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/trips/{id}/reschedule

Reschedule a trip’s departure

Sets a new departure time and shifts every not-yet-served stop by the same delta. Only a scheduled trip can move — a running or finished trip’s plan is a record of what happened. The reason is required. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
plannedStartTimerequiredstringpattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$
reasonrequiredstringmin length 1 · max length 160
notestringmax length 500
expectedRevinteger

Responses

  • 201Trip rescheduled
    FieldTypeDescription
    idnumberTrip ID; 0 or omitted on createe.g. 91
    codestringnullableTrip codee.g. "TR-2026-0630-004"
    routeIdnumberID of the route this trip executese.g. 4
    datestringDate of the trip (YYYY-MM-DD)e.g. "2026-06-30"
    driverIdnumbernullableID of the assigned driver (driver.id)e.g. 3
    vehicleIdnumbernullableID of the assigned vehiclee.g. 7
    statusstringValues: scheduledin_progresscompletedcancellede.g. "scheduled"
    plannedStartTimestringnullablePlanned start time (HH:mm:ss)e.g. "07:00:00"
    plannedEndTimestringnullablePlanned end time (HH:mm:ss)e.g. "07:45:00"
    passengersCountnumberCount of passengers assigned to this tripe.g. 22
    legLabelstringnullableOperator label for this leg of the route on the day ('Sáng', 'Chiều')e.g. "Sáng 2"
    cancelReasonstringnullableWhy the trip was cancelled. Null on live trips, and on rows cancelled before the column existed — rendered as “not recorded”, never guessed.e.g. "Sự cố phương tiện"
    cancelNotestringnullableNote sent with the cancellation
    rescheduleReasonstringnullableWhy the departure was last moved
    originalStartTimestringnullableDeparture before the first reschedule, so the log can show what changede.g. "07:45:00"
    revnumberRevision of the trip (row_version), bumped by every write. Send it back as expectedRev on a write; a stale value answers 409 STALE_TRIPe.g. 3
    needsReassignmentbooleanTrue when a resource on the trip has an approved unavailability overlapping it (see reassignmentFlags)e.g. false
    reassignmentFlagsobject[]Open reassignment flags of the trip
    reassignmentFlags[].idstring
    reassignmentFlags[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    reassignmentFlags[].resourceTypestringValues: drivermonitorvehicleteacher
    reassignmentFlags[].resourceIdnumber
    reassignmentFlags[].unavailabilityIdnumber
    reassignmentFlags[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    reassignmentFlags[].fromstringe.g. "2026-11-03T00:00"
    reassignmentFlags[].tostringe.g. "2026-11-05T00:00"
    reassignmentFlags[].flaggedAtstringISO instant
    reassignmentFlags[].severitystringurgent = short notice (BD-R3-03): a driver block reaching a trip in progress, or a published trip due to start within the tenant’s short-notice window (driver-app › unavailability.short_notice_hours, default 12). Shown above every normal flag.Values: normalurgent
    reassignmentFlags[].codestringnullableDRIVER_UNAVAILABLE_SHORT_NOTICE on an urgent flag; null otherwise.Values: DRIVER_UNAVAILABLE_SHORT_NOTICE
    reassignmentFlags[].escalatedAtstringnullableISO instant the unresolved urgent flag was escalated to the operations lead; null = not escalated.
    availabilityWarningsobject[]On an assignment write only: pending unavailability overlapping the trip (the write went through)
    availabilityWarnings[].codestringValues: RESOURCE_UNAVAILABILITY_PENDING
    availabilityWarnings[].tripIdstring
    availabilityWarnings[].rolestringValues: driverbackup_drivervehiclemonitor_primarymonitor_backupresponsible
    availabilityWarnings[].resourceTypestringValues: drivermonitorvehicleteacher
    availabilityWarnings[].resourceIdnumber
    availabilityWarnings[].unavailabilityIdnumber
    availabilityWarnings[].reasonstringValues: leavesicktrainingmaintenanceinspectionother
    availabilityWarnings[].fromstringe.g. "2026-11-03T00:00"
    availabilityWarnings[].tostringe.g. "2026-11-04T00:00"
  • 400
    Example
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Example
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Trip is not scheduled — it is running, finished, or cancelled

    expectedRev is older than the trip: nothing was written; params name the changed fields, who changed them and when

    A resource put on the trip has an approved unavailability overlapping it (params: resourceType, resourceId, unavailabilityId, reason, from, to, tripId, role)

    Example
    {
      "type": "https://stracker.io/errors/resource-unavailable",
      "title": "Resource unavailable",
      "status": 409,
      "detail": "Resource unavailable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RESOURCE_UNAVAILABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

PUT/v1/trips/{id}/stops

Replace a trip’s stop list

Rewrites the running order of one trip: array position becomes sequence, missing rows are removed, and a row may be marked skipped to drop it from this trip while keeping the record that it was planned. The ROUTE is never touched. Stops the vehicle has already reached cannot be moved, retimed or skipped, and must be resent unchanged. Also reachable with an OAuth access token carrying trips:write; send an Idempotency-Key header to make retries safe.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
stopsrequiredobject[]min items 2 · max items 80
stops[].stopIdrequiredinteger
stops[].expectedArrivalTimerequiredstringpattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$
stops[].expectedDepartureTimestringnullablepattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$
stops[].skippedbooleandefault false
stops[].contactNamestringnullablemax length 120
stops[].contactPhonestringnullablemax length 30 · pattern ^[0-9+().\s-]*$
stops[].contactNotestringnullablemax length 255

Responses

  • 200Updated stop list, in running order
    FieldTypeDescription
    idnumbere.g. 41
    stopIdnumbere.g. 7
    stopNamestringnullablee.g. "Ngã tư Lê Lợi"
    sequencenumbernullableRunning order; null when never sequencede.g. 1
    expectedArrivalTimestringnullablee.g. "06:42:00"
    actualArrivalTimestringnullablee.g. "06:44:00"
    expectedDepartureTimestringnullablee.g. "06:43:00"
    actualDepartureTimestringnullablee.g. "06:45:00"
    arrivedbooleane.g. true
    riderCountnumbere.g. 3
    latnumbernullablee.g. 10.776889
    lngnumbernullablee.g. 106.700806
    ridersWaitingnumbere.g. 2
    ridersPickedUpnumbere.g. 1
    delayMinutesnumbernullablee.g. 1
    skippedbooleane.g. false
    contactobjectnullableThe stop contact for this trip: trip_stop.contact_* when set, else the stop's contact_*; null when neither has a name or a phone
    contact.namestringnullablee.g. "Bác bảo vệ cổng A"
    contact.phonestringnullablee.g. "0901234567"
    contact.notestringnullablee.g. "Gọi trước 5 phút"
  • 400
    Example
    {
      "type": "https://stracker.io/errors/bad-request",
      "title": "Bad request",
      "status": 400,
      "detail": "Bad request",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "BAD_REQUEST"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Write/Owner permission for trips, or owns a different trip
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Trip does not exist
    Example
    {
      "type": "https://stracker.io/errors/trip-not-found",
      "title": "Trip not found",
      "status": 404,
      "detail": "Trip not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_NOT_FOUND"
    }
  • 409Trip has finished or been cancelled, the edit would move an already-served stop, or it would remove a stop riders were already notified about (mark it skipped instead)
    Example
    {
      "type": "https://stracker.io/errors/trip-invalid-state-transition",
      "title": "Trip invalid state transition",
      "status": 409,
      "detail": "Trip invalid state transition",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "TRIP_INVALID_STATE_TRANSITION"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Vehicles

GET/v1/vehicles

List vehicles

Returns a paginated, searchable list of vehicles, optionally filtered by status, transport company (tenant), depot, or source (own / hire), scoped to the caller when using the Owner permission.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 300 · default 100
searchKeywordquerystringmin length 1
orderBysquerystringmin length 1
statusquerystringValues: in_servicemaintenanceout_of_serviceretired
transportCompanyIdqueryinteger
depotIdqueryinteger
readinessquerystringValues: runnableblockeddue_soon
unassignedqueryboolean
sourcequerystringValues: ownhire
hireWatchqueryboolean

Responses

  • 200Paginated list of vehicles
    FieldTypeDescription
    dataobject[]
    data[].numberstringInternal fleet number/codee.g. "XE-07"
    data[].namestringDisplay name for the vehiclee.g. "Bus 07"
    data[].regoNumberstringVietnamese vehicle registration plate numbere.g. "51F-123.45"
    data[].brandstringVehicle manufacturere.g. "Thaco"
    data[].modelstringVehicle modele.g. "Universe"
    data[].yearintegerModel yeare.g. 2021
    data[].vinstringVehicle identification number (VIN)e.g. "1HGCM82633A004352"
    data[].capacitynumberPassenger seating capacitye.g. 45
    data[].picturestringStored filename/UUID of the vehicle picturee.g. "a1b2c3d4-vehicle.jpg"
    data[].pictureBase64stringBase64-encoded vehicle picture upload (URL-safe)
    data[].transportCompanyIdnumberID of the transport company that owns this vehiclee.g. 3
    data[].depotIdintegerID of the depot this vehicle is based ate.g. 2
    data[].statusstringValues: in_servicemaintenanceout_of_serviceretirede.g. "in_service"
    data[].vehicleTypestringValues: buscoachvanminibusothere.g. "bus"
    data[].fuelTypestringValues: dieselpetrolelectrichybridlpghydrogene.g. "diesel"
    data[].transmissionstringValues: manualautomatice.g. "manual"
    data[].groupIdnumberLegacy vehicle grouping id (no live lookup table)e.g. 1
    data[].currentOdometerKmintegerMost recent odometer reading, in kilometrese.g. 84210
    data[].nextServiceDatestringNext scheduled service date (YYYY-MM-DD)e.g. "2026-09-01"
    data[].nextServiceKmintegerOdometer reading at which the next service is duee.g. 90000
    data[].serviceIntervalKmintegerDistance between scheduled services, in kilometrese.g. 10000
    data[].nextInspectionDatestringNext roadworthy/compliance inspection due datee.g. "2026-08-15"
    data[].registrationExpirystringRegistration (rego) expiry datee.g. "2027-01-01"
    data[].insuranceExpirystringInsurance policy expiry datee.g. "2027-01-01"
    data[].latnumberLast known latitude (read-only, GPS heartbeat)e.g. 10.762622
    data[].lngnumberLast known longitude (read-only, GPS heartbeat)e.g. 106.660172
    data[].descriptionstringFree-text notes about the vehiclee.g. "45-seat coach for long routes"
    data[].documentsCountnumberCount of documents attached to this vehiclee.g. 3
    data[].payloadKgintegernullableGoods payload in kg; null = not recordede.g. 5000
    data[].palletCapacityintegernullablePallet places; null = not recordede.g. 14
    data[].isRefrigeratedbooleannullableRefrigerated body; null = not recordede.g. false
    data[].readinessobjectThe single server-side dispatch verdict
    data[].readiness.canRunbooleanWhether this vehicle may be dispatched todaye.g. false
    data[].readiness.blockersobject[]Every condition that fails; empty when canRun
    data[].readiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    data[].readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    data[].readiness.blockers[].severitystringValues: blockingadvisorye.g. "blocking"
    data[].readiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    data[].readiness.blockers[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    data[].readiness.blockers[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    data[].readiness.warningsobject[]Conditions about to fail (≤30 days / ≤1000 km; a hire contract warns from 60 days before it ends)
    data[].readiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    data[].readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    data[].readiness.warnings[].severitystringValues: blockingadvisorye.g. "blocking"
    data[].readiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    data[].readiness.warnings[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    data[].readiness.warnings[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    data[].readiness.maintenanceTrackedbooleanFalse when the tenant has no maintenance extension — the km cycle is then not tracked at all. Hired vehicles never get a km-cycle verdict either way: the vendor owns their maintenance.e.g. true
    data[].readiness.requiredDocumentTypesstring[]vehicle_document.doc_type codes this vehicle must hold, in the order the documents tab prints them. The tab is a CHECKLIST: a required type with no row on file is drawn as a MISSING row, which is exactly the case an operator opens the tab for. The client renders this list and never re-derives it.
    data[].inspectionobjectSafety-inspection expiry and its countdown
    data[].inspection.validUntilstringnullablee.g. "2026-11-30"
    data[].inspection.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    data[].insuranceobjectInsurance expiry and its countdown
    data[].insurance.validUntilstringnullablee.g. "2026-11-30"
    data[].insurance.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    data[].nextServiceobjectnullableNull when the tenant has no maintenance extension — hide the column, do not render 0
    data[].nextService.dueKmintegerOdometer reading at which the next service falls duee.g. 90000
    data[].nextService.remainingKmintegerKilometres left; negative once overduee.g. 1200
    data[].nextService.cycleKmintegerConfigured distance between servicese.g. 10000
    data[].assignmentobjectnullableToday's driver/route, when assigned
    data[].assignment.driverIdintegernullablee.g. 12
    data[].assignment.driverNamestringnullablee.g. "Nguyễn Thu Hà"
    data[].assignment.routeLabelstringnullablee.g. "Tuyến 12 · Buổi sáng"
    data[].assignment.tripIdintegernullableTrip the assignment came frome.g. 4821
    data[].utilizationobjectSeven day-flags, oldest first
    data[].utilization.last7Daysstring[]1 = ran at least one trip that day
    data[].costobjectRunning cost; nulls when the timeline has too little data
    data[].cost.perKmintegernullableOperating cost per kilometre, tenant currencye.g. 9200
    data[].cost.fuelPer100KmnumbernullableLitres per 100 kme.g. 18.4
    data[].cost.annualTotalstringnullableTotal recorded cost over the last 12 monthse.g. "61340000.00"
    data[].cost.breakdownobject[]
    data[].cost.breakdown[].categorystringEvent kind the cost was recorded undere.g. "fuel"
    data[].cost.breakdown[].amountstringRecorded amount, tenant currencye.g. "31940000.00"
    data[].cost.breakdown[].sharePctnumberShare of recorded cost, 0-100e.g. 52
    data[].cost.breakdown[].perKmintegernullableThis slice per kilometre; null without witnessed distancee.g. 4780
    data[].dailyCheckobjectToday's driver walkaround, if recorded
    data[].dailyCheck.recordedAtstringnullableWhen a driver completed today's check (ISO instant); null when none is recorded todaye.g. "2026-09-17T23:12:00.000Z"
    data[].sourceobjectOwn or hired, with the vendor and hire-contract terms when hired
    data[].source.kindstringValues: ownhire
    data[].source.vendorobjectnullable
    data[].source.vendor.idnumbere.g. 3
    data[].source.vendor.namestringe.g. "Hồng Phát Transport"
    data[].source.vendor.contactNamestringnullablee.g. "Trần Văn Hải"
    data[].source.vendor.phonestringnullablee.g. "0903 111 222"
    data[].source.vendor.emailstringnullablee.g. "dieudo@hongphat.vn"
    data[].source.contractobjectnullable
    data[].source.contract.idnumbere.g. 12
    data[].source.contract.codestringe.g. "HĐ-2026/14"
    data[].source.contract.statusstringValues: draftpendingactiveterminated
    data[].source.contract.startsOnstringISO date (YYYY-MM-DD)e.g. "2026-01-01"
    data[].source.contract.endsOnstringnullableNull while open-endede.g. "2026-12-31"
    data[].source.contract.daysToEndnumbernullableWhole days until endsOn; negative once past; null when open-endede.g. 112
    data[].source.contract.statestringServer-derived validity label; the client never compares dates itselfValues: activedue_soonexpirednot_active
    data[].source.contract.linkedVehiclesnumberLive vehicles attached to this contracte.g. 2
    data[].source.contract.dailyRatestringnullableThe contract's own daily ratee.g. "3100000.00"
    data[].source.dailyRatestringnullableEffective daily rate: the per-vehicle override, else the contract rate. Decimal string.e.g. "2400000.00"
    data[].source.rateOverriddenbooleanTrue when the vehicle carries its own rate instead of the contract rate
    data[].source.serviceScopestringnullablee.g. "Đưa rước 2 chiều · T2–T6"
    data[].source.serviceScopeDerivedbooleanTrue when serviceScope was taken from the contract, not set on the vehicle
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/vehicles/{id}

Get a vehicle

Returns the vehicle detail aggregate by its primary key.

Parameters

FieldTypeDescription
idpathrequiredintegerNumeric id of the vehicle, as returned in the id field of the list endpoint.

Responses

  • 200Vehicle found
    FieldTypeDescription
    numberstringInternal fleet number/codee.g. "XE-07"
    namestringDisplay name for the vehiclee.g. "Bus 07"
    regoNumberstringVietnamese vehicle registration plate numbere.g. "51F-123.45"
    brandstringVehicle manufacturere.g. "Thaco"
    modelstringVehicle modele.g. "Universe"
    yearintegerModel yeare.g. 2021
    vinstringVehicle identification number (VIN)e.g. "1HGCM82633A004352"
    capacitynumberPassenger seating capacitye.g. 45
    picturestringStored filename/UUID of the vehicle picturee.g. "a1b2c3d4-vehicle.jpg"
    pictureBase64stringBase64-encoded vehicle picture upload (URL-safe)
    transportCompanyIdnumberID of the transport company that owns this vehiclee.g. 3
    depotIdintegerID of the depot this vehicle is based ate.g. 2
    statusstringValues: in_servicemaintenanceout_of_serviceretirede.g. "in_service"
    vehicleTypestringValues: buscoachvanminibusothere.g. "bus"
    fuelTypestringValues: dieselpetrolelectrichybridlpghydrogene.g. "diesel"
    transmissionstringValues: manualautomatice.g. "manual"
    groupIdnumberLegacy vehicle grouping id (no live lookup table)e.g. 1
    currentOdometerKmintegerMost recent odometer reading, in kilometrese.g. 84210
    nextServiceDatestringNext scheduled service date (YYYY-MM-DD)e.g. "2026-09-01"
    nextServiceKmintegerOdometer reading at which the next service is duee.g. 90000
    serviceIntervalKmintegerDistance between scheduled services, in kilometrese.g. 10000
    nextInspectionDatestringNext roadworthy/compliance inspection due datee.g. "2026-08-15"
    registrationExpirystringRegistration (rego) expiry datee.g. "2027-01-01"
    insuranceExpirystringInsurance policy expiry datee.g. "2027-01-01"
    latnumberLast known latitude (read-only, GPS heartbeat)e.g. 10.762622
    lngnumberLast known longitude (read-only, GPS heartbeat)e.g. 106.660172
    descriptionstringFree-text notes about the vehiclee.g. "45-seat coach for long routes"
    documentsCountnumberCount of documents attached to this vehiclee.g. 3
    payloadKgintegernullableGoods payload in kg; null = not recordede.g. 5000
    palletCapacityintegernullablePallet places; null = not recordede.g. 14
    isRefrigeratedbooleannullableRefrigerated body; null = not recordede.g. false
    readinessobjectThe single server-side dispatch verdict
    readiness.canRunbooleanWhether this vehicle may be dispatched todaye.g. false
    readiness.blockersobject[]Every condition that fails; empty when canRun
    readiness.blockers[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    readiness.blockers[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    readiness.blockers[].severitystringValues: blockingadvisorye.g. "blocking"
    readiness.blockers[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    readiness.blockers[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    readiness.blockers[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    readiness.warningsobject[]Conditions about to fail (≤30 days / ≤1000 km; a hire contract warns from 60 days before it ends)
    readiness.warnings[].codestringStable machine code; the client maps it to vehicles.readiness.<code>e.g. "INSPECTION_EXPIRED"
    readiness.warnings[].labelstringDeveloper-facing English fallback. Never parsed — translate from code instead.e.g. "Safety inspection expired"
    readiness.warnings[].severitystringValues: blockingadvisorye.g. "blocking"
    readiness.warnings[].daysLeftnumberDays until (negative: past) the expirye.g. -6
    readiness.warnings[].remainingKmnumberKilometres until (negative: past) the next servicee.g. 380
    readiness.warnings[].defectIdnumberOriginating vehicle_defect.id, for defect-driven reasons
    readiness.maintenanceTrackedbooleanFalse when the tenant has no maintenance extension — the km cycle is then not tracked at all. Hired vehicles never get a km-cycle verdict either way: the vendor owns their maintenance.e.g. true
    readiness.requiredDocumentTypesstring[]vehicle_document.doc_type codes this vehicle must hold, in the order the documents tab prints them. The tab is a CHECKLIST: a required type with no row on file is drawn as a MISSING row, which is exactly the case an operator opens the tab for. The client renders this list and never re-derives it.
    inspectionobjectSafety-inspection expiry and its countdown
    inspection.validUntilstringnullablee.g. "2026-11-30"
    inspection.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    insuranceobjectInsurance expiry and its countdown
    insurance.validUntilstringnullablee.g. "2026-11-30"
    insurance.daysLeftintegerWhole days left; negative once expired. Null when no date is recorded.e.g. 64
    nextServiceobjectnullableNull when the tenant has no maintenance extension — hide the column, do not render 0
    nextService.dueKmintegerOdometer reading at which the next service falls duee.g. 90000
    nextService.remainingKmintegerKilometres left; negative once overduee.g. 1200
    nextService.cycleKmintegerConfigured distance between servicese.g. 10000
    assignmentobjectnullableToday's driver/route, when assigned
    assignment.driverIdintegernullablee.g. 12
    assignment.driverNamestringnullablee.g. "Nguyễn Thu Hà"
    assignment.routeLabelstringnullablee.g. "Tuyến 12 · Buổi sáng"
    assignment.tripIdintegernullableTrip the assignment came frome.g. 4821
    utilizationobjectSeven day-flags, oldest first
    utilization.last7Daysstring[]1 = ran at least one trip that day
    costobjectRunning cost; nulls when the timeline has too little data
    cost.perKmintegernullableOperating cost per kilometre, tenant currencye.g. 9200
    cost.fuelPer100KmnumbernullableLitres per 100 kme.g. 18.4
    cost.annualTotalstringnullableTotal recorded cost over the last 12 monthse.g. "61340000.00"
    cost.breakdownobject[]
    cost.breakdown[].categorystringEvent kind the cost was recorded undere.g. "fuel"
    cost.breakdown[].amountstringRecorded amount, tenant currencye.g. "31940000.00"
    cost.breakdown[].sharePctnumberShare of recorded cost, 0-100e.g. 52
    cost.breakdown[].perKmintegernullableThis slice per kilometre; null without witnessed distancee.g. 4780
    dailyCheckobjectToday's driver walkaround, if recorded
    dailyCheck.recordedAtstringnullableWhen a driver completed today's check (ISO instant); null when none is recorded todaye.g. "2026-09-17T23:12:00.000Z"
    sourceobjectOwn or hired, with the vendor and hire-contract terms when hired
    source.kindstringValues: ownhire
    source.vendorobjectnullable
    source.vendor.idnumbere.g. 3
    source.vendor.namestringe.g. "Hồng Phát Transport"
    source.vendor.contactNamestringnullablee.g. "Trần Văn Hải"
    source.vendor.phonestringnullablee.g. "0903 111 222"
    source.vendor.emailstringnullablee.g. "dieudo@hongphat.vn"
    source.contractobjectnullable
    source.contract.idnumbere.g. 12
    source.contract.codestringe.g. "HĐ-2026/14"
    source.contract.statusstringValues: draftpendingactiveterminated
    source.contract.startsOnstringISO date (YYYY-MM-DD)e.g. "2026-01-01"
    source.contract.endsOnstringnullableNull while open-endede.g. "2026-12-31"
    source.contract.daysToEndnumbernullableWhole days until endsOn; negative once past; null when open-endede.g. 112
    source.contract.statestringServer-derived validity label; the client never compares dates itselfValues: activedue_soonexpirednot_active
    source.contract.linkedVehiclesnumberLive vehicles attached to this contracte.g. 2
    source.contract.dailyRatestringnullableThe contract's own daily ratee.g. "3100000.00"
    source.dailyRatestringnullableEffective daily rate: the per-vehicle override, else the contract rate. Decimal string.e.g. "2400000.00"
    source.rateOverriddenbooleanTrue when the vehicle carries its own rate instead of the contract rate
    source.serviceScopestringnullablee.g. "Đưa rước 2 chiều · T2–T6"
    source.serviceScopeDerivedbooleanTrue when serviceScope was taken from the contract, not set on the vehicle
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403Caller lacks the Read/Owner permission for vehicles
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404Vehicle does not exist
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

Webhooks

GET/v1/webhooks/event-types

List webhook event types

Every event type a subscription can select, with its labels and the OAuth scope an app needs. available is true when the caller may subscribe to it: a signed-in user needs the permission behind the event (for example ops:trips:view), an app needs the event’s read scope and never gets billing events.

Parameters

No parameters.

Responses

  • 200The catalogue
    FieldTypeDescription
    dataobject[]
    data[].typestringe.g. "trip.completed"
    data[].groupstringValues: tripsinvoicespaymentssubscriptionsextensionswebhooks
    data[].labelsobject
    data[].scopestringnullableOAuth scope an app needs to receive it.e.g. "trips:read"
    data[].availablebooleanTrue when the caller may subscribe to this event.
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }

GET/v1/webhooks/messages

List webhook messages

The events queued for the tenant’s webhook subscriptions, newest first (an app sees only its own subscriptions’ messages). Filter by subscription, status or event type.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 100 · default 20
statusquerystringValues: pendingdeliveredfailedcancelled
eventTypequerystringmin length 1 · max length 80
subscriptionIdqueryinteger

Responses

  • 200PageDto of WebhookMessageDto
    FieldTypeDescription
    dataobject[]
    data[].idnumber
    data[].subscriptionIdnumber
    data[].subscriptionNamestring
    data[].eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    data[].eventTypestringe.g. "trip.completed"
    data[].statusstringValues: pendingdeliveredfailedcancelled
    data[].attemptCountnumber
    data[].nextAttemptAtstring (date-time)nullable
    data[].lastAttemptAtstring (date-time)nullable
    data[].lastStatusCodenumbernullable
    data[].lastStatusClassstringnullableValues: 2xx3xx4xx5xxtimeoutnetworkblocked
    data[].deliveredAtstring (date-time)nullable
    data[].cancelReasonstringnullableWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    data[].createdAtstring (date-time)
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }

GET/v1/webhooks/messages/{id}

Get a webhook message

One message with every delivery attempt and the exact payload the receiver gets.

Parameters

FieldTypeDescription
idpathrequiredinteger

Responses

  • 200The message, its attempts and its payload
    FieldTypeDescription
    idnumber
    subscriptionIdnumber
    subscriptionNamestring
    eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    eventTypestringe.g. "trip.completed"
    statusstringValues: pendingdeliveredfailedcancelled
    attemptCountnumber
    nextAttemptAtstring (date-time)nullable
    lastAttemptAtstring (date-time)nullable
    lastStatusCodenumbernullable
    lastStatusClassstringnullableValues: 2xx3xx4xx5xxtimeoutnetworkblocked
    deliveredAtstring (date-time)nullable
    cancelReasonstringnullableWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    createdAtstring (date-time)
    attemptsobject[]Oldest first.
    attempts[].attemptNonumber
    attempts[].triggerstringValues: automanualtest
    attempts[].attemptedAtstring (date-time)
    attempts[].statusCodenumbernullable
    attempts[].statusClassstringValues: 2xx3xx4xx5xxtimeoutnetworkblocked
    attempts[].latencyMsnumbernullable
    attempts[].responseExcerptstringnullableFirst characters of a non-2xx response body.
    payloadobjectThe envelope as the receiver gets it: id, type, createdAt, apiVersion, data (and tenant.installId for partner apps).
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }

POST/v1/webhooks/messages/{id}/redeliver

Redeliver a webhook message

Sends a delivered, failed or cancelled message again now. The event id is unchanged, so a receiver that dedupes on it sees a repeat. Only within the 30-day retention and while the subscription is enabled.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Responses

  • 200The message, back to pending with an attempt queued
    FieldTypeDescription
    idnumber
    subscriptionIdnumber
    subscriptionNamestring
    eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    eventTypestringe.g. "trip.completed"
    statusstringValues: pendingdeliveredfailedcancelled
    attemptCountnumber
    nextAttemptAtstring (date-time)nullable
    lastAttemptAtstring (date-time)nullable
    lastStatusCodenumbernullable
    lastStatusClassstringnullableValues: 2xx3xx4xx5xxtimeoutnetworkblocked
    deliveredAtstring (date-time)nullable
    cancelReasonstringnullableWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    createdAtstring (date-time)
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription is disabled
    Example
    {
      "type": "https://stracker.io/errors/webhook-subscription-disabled",
      "title": "Webhook subscription disabled",
      "status": 409,
      "detail": "Webhook subscription disabled",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_DISABLED"
    }
  • 410The message is past its retention window
    Example
    {
      "type": "https://stracker.io/errors/webhook-message-expired",
      "title": "Webhook message expired",
      "status": 410,
      "detail": "Webhook message expired",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_MESSAGE_EXPIRED"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/webhooks/subscriptions

List webhook subscriptions

Newest first. A signed-in user sees every subscription of the tenant, the tenant’s own and the ones apps own (owner narrows). Signing secrets are never listed.

Parameters

FieldTypeDescription
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 100 · default 20
searchKeywordquerystringmin length 1 · max length 120
statusquerystringValues: activedisabled
ownerquerystringValues: tenantapp

Responses

  • 200PageDto of WebhookSubscriptionDto
    FieldTypeDescription
    dataobject[]
    data[].idnumber
    data[].namestring
    data[].descriptionstringnullable
    data[].urlstring
    data[].eventsstring[]
    data[].statusstringValues: activedisabled
    data[].disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    data[].disabledAtstring (date-time)nullable
    data[].ownerobject
    data[].owner.kindstringValues: tenantapp
    data[].owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    data[].owner.namestringApp name (apps only).
    data[].owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    data[].legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    data[].secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    data[].secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    data[].consecutiveFailuresnumber
    data[].failingSincestring (date-time)nullable
    data[].lastSuccessAtstring (date-time)nullable
    data[].lastFailureAtstring (date-time)nullable
    data[].createdAtstring (date-time)
    data[].createdBynumbernullable
    data[].updatedAtstring (date-time)nullable
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }

POST/v1/webhooks/subscriptions

Create a webhook subscription

Registers an https endpoint for the chosen event types. The signing secret is in this response only: store it now. A signed-in user creates a tenant subscription; an app (OAuth token with webhooks:manage) creates one it owns. At most 20 per tenant and 10 per app. Send an Idempotency-Key header to make retries safe: a replay within 24 hours answers with the stored subscription but without secret (it is never cached), so a caller that lost the first response rotates the secret.

Parameters

FieldTypeDescription
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours, without the signing secret (it is shown once, in the first response); the same key with another body is a 422.

Request body application/json

FieldTypeDescription
namerequiredstringmin length 1 · max length 120
urlrequiredstringmin length 1 · max length 500
descriptionstringnullablemax length 500
eventsrequiredstring[]Values: trip.createdtrip.rescheduledtrip.cancelledtrip.startedtrip.completedinvoice.createdinvoice.paidinvoice.payment_failedinvoice.refundedpayment.completedpayment.failedsubscription.createdsubscription.upgradedsubscription.canceledextension.installedextension.upgradedmin items 1 · max items 30

Responses

  • 201The subscription and its signing secret (shown once)
    FieldTypeDescription
    subscriptionobject
    subscription.idnumber
    subscription.namestring
    subscription.descriptionstringnullable
    subscription.urlstring
    subscription.eventsstring[]
    subscription.statusstringValues: activedisabled
    subscription.disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    subscription.disabledAtstring (date-time)nullable
    subscription.ownerobject
    subscription.owner.kindstringValues: tenantapp
    subscription.owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    subscription.owner.namestringApp name (apps only).
    subscription.owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    subscription.legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    subscription.secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    subscription.secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    subscription.consecutiveFailuresnumber
    subscription.failingSincestring (date-time)nullable
    subscription.lastSuccessAtstring (date-time)nullable
    subscription.lastFailureAtstring (date-time)nullable
    subscription.createdAtstring (date-time)
    subscription.createdBynumbernullable
    subscription.updatedAtstring (date-time)nullable
    secretstringThe signing secret. Shown once: store it now.e.g. "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • 400Invalid body

    The URL is refused (params.reason: 'scheme', 'port', 'credentials', 'fragment', 'unresolvable' or 'private_address')

    The request has no tenant scope (platform context)

    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403The caller may not subscribe to one or more events (params.events)
    Example
    {
      "type": "https://stracker.io/errors/webhook-event-not-allowed",
      "title": "Webhook event not allowed",
      "status": 403,
      "detail": "Webhook event not allowed",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_EVENT_NOT_ALLOWED"
    }
  • 409The owner already holds the maximum number of subscriptions (params.limit)
    Example
    {
      "type": "https://stracker.io/errors/webhook-subscription-limit-reached",
      "title": "Webhook subscription limit reached",
      "status": 409,
      "detail": "Webhook subscription limit reached",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/webhooks/subscriptions/{id}

Get a webhook subscription

Parameters

FieldTypeDescription
idpathrequiredinteger

Responses

  • 200The subscription
    FieldTypeDescription
    idnumber
    namestring
    descriptionstringnullable
    urlstring
    eventsstring[]
    statusstringValues: activedisabled
    disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    disabledAtstring (date-time)nullable
    ownerobject
    owner.kindstringValues: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)nullable
    lastSuccessAtstring (date-time)nullable
    lastFailureAtstring (date-time)nullable
    createdAtstring (date-time)
    createdBynumbernullable
    updatedAtstring (date-time)nullable
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }

PATCH/v1/webhooks/subscriptions/{id}

Update a webhook subscription

Changes the name, description, URL or events, or switches the legacy signature off (legacySignature: false). A subscription an app owns cannot be edited by a signed-in user (it can be enabled, disabled or deleted). The signing secret is not changed here: use rotate-secret.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Request body application/json

FieldTypeDescription
namestringmin length 1 · max length 120
urlstringmin length 1 · max length 500
descriptionstringnullablemax length 500
eventsstring[]Values: trip.createdtrip.rescheduledtrip.cancelledtrip.startedtrip.completedinvoice.createdinvoice.paidinvoice.payment_failedinvoice.refundedpayment.completedpayment.failedsubscription.createdsubscription.upgradedsubscription.canceledextension.installedextension.upgradedmin items 1 · max items 30
legacySignaturebooleanValues: false

Responses

  • 200The updated subscription
    FieldTypeDescription
    idnumber
    namestring
    descriptionstringnullable
    urlstring
    eventsstring[]
    statusstringValues: activedisabled
    disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    disabledAtstring (date-time)nullable
    ownerobject
    owner.kindstringValues: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)nullable
    lastSuccessAtstring (date-time)nullable
    lastFailureAtstring (date-time)nullable
    createdAtstring (date-time)
    createdBynumbernullable
    updatedAtstring (date-time)nullable
  • 400Invalid body

    The URL is refused (params.reason: 'scheme', 'port', 'credentials', 'fragment', 'unresolvable' or 'private_address')

    The request has no tenant scope (platform context)

    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403The caller may not subscribe to one or more of the added events (params.events)
    Example
    {
      "type": "https://stracker.io/errors/webhook-event-not-allowed",
      "title": "Webhook event not allowed",
      "status": 403,
      "detail": "Webhook event not allowed",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_EVENT_NOT_ALLOWED"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription belongs to an app; a signed-in user may not edit it
    Example
    {
      "type": "https://stracker.io/errors/webhook-subscription-not-editable",
      "title": "Webhook subscription not editable",
      "status": 409,
      "detail": "Webhook subscription not editable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_NOT_EDITABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

DELETE/v1/webhooks/subscriptions/{id}

Delete a webhook subscription

Soft delete: no more deliveries, pending messages are cancelled and the signing secrets are removed. The delivery log stays readable for its retention period.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Responses

  • 200The id and deleted: true
    FieldTypeDescription
    idnumber
    deletedbooleanValues: true
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/webhooks/subscriptions/{id}/disable

Disable a webhook subscription

Stops deliveries (reason manual) and cancels the messages still waiting to be sent. A signed-in user may disable an app’s subscription; an app only its own.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Responses

  • 200The subscription
    FieldTypeDescription
    idnumber
    namestring
    descriptionstringnullable
    urlstring
    eventsstring[]
    statusstringValues: activedisabled
    disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    disabledAtstring (date-time)nullable
    ownerobject
    owner.kindstringValues: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)nullable
    lastSuccessAtstring (date-time)nullable
    lastFailureAtstring (date-time)nullable
    createdAtstring (date-time)
    createdBynumbernullable
    updatedAtstring (date-time)nullable
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/webhooks/subscriptions/{id}/enable

Enable a webhook subscription

Turns a disabled subscription back on and resets its failure counters. The URL and the owner are checked again first; a subscription whose owner is no longer entitled stays disabled.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Responses

  • 200The subscription
    FieldTypeDescription
    idnumber
    namestring
    descriptionstringnullable
    urlstring
    eventsstring[]
    statusstringValues: activedisabled
    disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    disabledAtstring (date-time)nullable
    ownerobject
    owner.kindstringValues: tenantapp
    owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    owner.namestringApp name (apps only).
    owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    consecutiveFailuresnumber
    failingSincestring (date-time)nullable
    lastSuccessAtstring (date-time)nullable
    lastFailureAtstring (date-time)nullable
    createdAtstring (date-time)
    createdBynumbernullable
    updatedAtstring (date-time)nullable
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The stored URL is refused now (params.reason)

    The owner is no longer entitled to receive events (params.reason, e.g. owner_revoked)

    Example
    {
      "type": "https://stracker.io/errors/webhook-subscription-not-editable",
      "title": "Webhook subscription not editable",
      "status": 409,
      "detail": "Webhook subscription not editable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_NOT_EDITABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

GET/v1/webhooks/subscriptions/{id}/messages

List the messages of a webhook subscription

The events queued for the subscription and how each delivery went, newest first.

Parameters

FieldTypeDescription
idpathrequiredinteger
pagequeryintegermin 1 · default 1
limitqueryintegermin 1 · max 100 · default 20
statusquerystringValues: pendingdeliveredfailedcancelled
eventTypequerystringmin length 1 · max length 80

Responses

  • 200PageDto of WebhookMessageDto
    FieldTypeDescription
    dataobject[]
    data[].idnumber
    data[].subscriptionIdnumber
    data[].subscriptionNamestring
    data[].eventIdstringStable across retries and redelivery: dedupe on it.e.g. "evt_01JD0000000000000000000000"
    data[].eventTypestringe.g. "trip.completed"
    data[].statusstringValues: pendingdeliveredfailedcancelled
    data[].attemptCountnumber
    data[].nextAttemptAtstring (date-time)nullable
    data[].lastAttemptAtstring (date-time)nullable
    data[].lastStatusCodenumbernullable
    data[].lastStatusClassstringnullableValues: 2xx3xx4xx5xxtimeoutnetworkblocked
    data[].deliveredAtstring (date-time)nullable
    data[].cancelReasonstringnullableWhy no attempt was made (status cancelled).e.g. "subscription_disabled"
    data[].createdAtstring (date-time)
    metaobject
    meta.pagenumber
    meta.limitnumber
    meta.itemCountnumber
    meta.pageCountnumber
    meta.hasPreviousPageboolean
    meta.hasNextPageboolean
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }

POST/v1/webhooks/subscriptions/{id}/rotate-secret

Rotate a webhook signing secret

Issues a new signing secret (in this response only). For 24 hours deliveries are signed with both the new and the old secret so the receiver can switch without a gap (a replay with the same Idempotency-Key omits secret: it is never cached); revokePreviousNow drops the old one at once. A signed-in user cannot rotate the secret of an app’s subscription.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours, without the signing secret (it is shown once, in the first response); the same key with another body is a 422.

Request body application/json

FieldTypeDescription
revokePreviousNowboolean

Responses

  • 200The subscription and the new signing secret (shown once)
    FieldTypeDescription
    subscriptionobject
    subscription.idnumber
    subscription.namestring
    subscription.descriptionstringnullable
    subscription.urlstring
    subscription.eventsstring[]
    subscription.statusstringValues: activedisabled
    subscription.disabledReasonstringnullableValues: manualauto_failuresowner_revoked
    subscription.disabledAtstring (date-time)nullable
    subscription.ownerobject
    subscription.owner.kindstringValues: tenantapp
    subscription.owner.clientIdstringPublic client id (apps only).e.g. "stc_aBcDeFgHiJkLmNoPqRsTuV"
    subscription.owner.namestringApp name (apps only).
    subscription.owner.partnerbooleanTrue for a partner app installed from the directory (apps only).
    subscription.legacySignaturebooleanPre-2026-11 subscription that still gets the old signature header and body keys until switched off.
    subscription.secretPrefixstringnullableFirst characters of the secret, for display.e.g. "whsec_aBcDeF"
    subscription.secretRotationEndsAtstring (date-time)nullableWhile set, the previous secret still signs next to the new one.
    subscription.consecutiveFailuresnumber
    subscription.failingSincestring (date-time)nullable
    subscription.lastSuccessAtstring (date-time)nullable
    subscription.lastFailureAtstring (date-time)nullable
    subscription.createdAtstring (date-time)
    subscription.createdBynumbernullable
    subscription.updatedAtstring (date-time)nullable
    secretstringThe signing secret. Shown once: store it now.e.g. "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • 400Invalid body

    The request has no tenant scope (platform context)

    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription belongs to an app; a signed-in user may not rotate its secret
    Example
    {
      "type": "https://stracker.io/errors/webhook-subscription-not-editable",
      "title": "Webhook subscription not editable",
      "status": 409,
      "detail": "Webhook subscription not editable",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_NOT_EDITABLE"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Per-client OAuth rate limit exceeded
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

POST/v1/webhooks/subscriptions/{id}/test

Send a test event

Sends one signed webhook.test event to the subscription and reports how the receiver answered. It is logged as a test delivery and never counts toward the automatic disabling of a failing subscription. At most 10 per minute.

Parameters

FieldTypeDescription
idpathrequiredinteger
Idempotency-KeyheaderstringA retried request with the same key replays the original answer for 24 hours; the same key with another body is a 422.

Responses

  • 200The outcome of the test delivery
    FieldTypeDescription
    deliveredboolean
    statusCodenumbernullable
    statusClassstringValues: 2xx3xx4xx5xxtimeoutnetworkblocked
    latencyMsnumber
    attemptedAtstring (date-time)
  • 400The request has no tenant scope (platform context)
    Example
    {
      "type": "https://stracker.io/errors/oauth-tenant-required",
      "title": "A tenant is required",
      "status": 400,
      "detail": "A tenant is required",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "OAUTH_TENANT_REQUIRED"
    }
  • 401
    Example
    {
      "type": "https://stracker.io/errors/auth-unauthorized",
      "title": "Unauthorized",
      "status": 401,
      "detail": "Unauthorized",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_UNAUTHORIZED"
    }
  • 403
    Example
    {
      "type": "https://stracker.io/errors/auth-forbidden",
      "title": "Forbidden",
      "status": 403,
      "detail": "Forbidden",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "AUTH_FORBIDDEN"
    }
  • 404
    Example
    {
      "type": "https://stracker.io/errors/not-found",
      "title": "Resource not found",
      "status": 404,
      "detail": "Resource not found",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "NOT_FOUND"
    }
  • 409The subscription is disabled
    Example
    {
      "type": "https://stracker.io/errors/webhook-subscription-disabled",
      "title": "Webhook subscription disabled",
      "status": 409,
      "detail": "Webhook subscription disabled",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "WEBHOOK_SUBSCRIPTION_DISABLED"
    }
  • 422The Idempotency-Key was already used with a different request body
    Example
    {
      "type": "https://stracker.io/errors/idempotency-key-reused",
      "title": "Idempotency-Key reused with different payload",
      "status": 422,
      "detail": "Idempotency-Key reused with different payload",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "IDEMPOTENCY_KEY_REUSED"
    }
  • 429Too many tests, or the per-client OAuth rate limit
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }

OAuth token

POST/v1/oauth/token

Issue an OAuth access token (client_credentials, authorization_code, refresh_token)

  • Scope none (public document)

Form body. A confidential client authenticates with Authorization: Basic base64(client_id:client_secret); a public client sends client_id and no secret. grant_type=client_credentials takes an optional scope inside the client's scope set. grant_type=authorization_code takes code, redirect_uri (exactly as in the authorize request) and the PKCE code_verifier. grant_type=refresh_token takes refresh_token and an optional narrower scope; the refresh token is single use and rotates (reusing one revokes the grant). Answers { access_token, token_type: "Bearer", expires_in, scope, refresh_token? }. Responses are never cacheable.

Client authentication. Client authentication: client_secret_basic (Authorization: Basic base64(client_id:client_secret)), private_key_jwt (client_assertion_type + client_assertion, ES256 or RS256) or, for a public client, client_id alone.

Parameters

No parameters.

Request body application/x-www-form-urlencoded

FieldTypeDescription
grant_typerequiredstringmin length 1 · max length 64
scopestringmax length 1000
client_idstringmin length 1 · max length 64
client_assertion_typestringmin length 1 · max length 128
client_assertionstringmin length 1 · max length 8192
codestringmin length 1 · max length 128
redirect_uristringmin length 1 · max length 500
code_verifierstringmin length 1 · max length 128
refresh_tokenstringmin length 1 · max length 128
tenantstringmin length 1 · max length 64

Responses

  • 200A new access token (and a rotated refresh token when offline_access was approved)
    FieldTypeDescription
    access_tokenstringES256-signed JWT (typ at+jwt)
    token_typestringe.g. "Bearer"
    expires_innumberLifetime in secondse.g. 1800
    scopestringThe scopes the token carriese.g. "trips:read drivers:read"
    refresh_tokenstringOnly for authorization_code (when offline_access was approved) and refresh_token
  • 400RFC 6749 5.2: invalid_request, invalid_grant, invalid_scope, unsupported_grant_type or unauthorized_client (for example {"error":"invalid_scope","error_description":"..."})
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "invalid_grant",
      "error_description": "The grant is invalid, expired, revoked or was issued to another client"
    }
  • 401RFC 6749 5.2: invalid_client, the same answer for an unknown client, a wrong, revoked or expired secret or client assertion, and a disabled client; carries WWW-Authenticate: Basic realm="stracker"
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "invalid_client",
      "error_description": "Client authentication failed"
    }
  • 429More than 30 requests a minute from one IP for one client; RFC 6749 temporarily_unavailable plus Retry-After
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }
  • 503RFC 6749 5.2: temporarily_unavailable, no signing key can sign right now or a revocation could not be recorded
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "temporarily_unavailable",
      "error_description": "The server cannot issue tokens right now"
    }

OAuth revocation

POST/v1/oauth/introspect

Introspect an OAuth access token or refresh token (RFC 7662)

  • Scope none (public document)

Form body token (+ optional token_type_hint, ignored). Requires Authorization: Basic base64(client_id:client_secret) of a confidential client. Answers { "active": false } for every token that is not live for the calling client (unknown, expired, revoked, another client's) and, for a live one, active, scope, client_id, token_type, exp, iat, sub, aud, iss, jti, tid (a refresh token: active, scope, client_id, exp, sub, tid). Responses are never cacheable.

Client authentication. Client authentication: client_secret_basic (Authorization: Basic base64(client_id:client_secret)), private_key_jwt (client_assertion_type + client_assertion, ES256 or RS256) or, for a public client, client_id alone.

Parameters

No parameters.

Request body application/x-www-form-urlencoded

FieldTypeDescription
tokenrequiredstringmin length 1 · max length 2048
token_type_hintstringmax length 64
client_assertion_typestringmin length 1 · max length 128
client_assertionstringmin length 1 · max length 8192

Responses

  • 200The token state
    FieldTypeDescription
    activebooleane.g. true
    scopestringe.g. "trips:read drivers:read"
    client_idstring
    token_typestringAccess tokens onlye.g. "Bearer"
    expnumberEpoch seconds
    iatnumberEpoch seconds; access tokens only
    substringUser id (string)
    audanyAccess tokens only
    issstringAccess tokens only
    jtistringAccess tokens only
    tidstringTenant id (string)
  • 400RFC 6749 5.2: invalid_request (not a form, token missing, a parameter repeated or unknown)
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "invalid_request",
      "error_description": "The request must be application/x-www-form-urlencoded"
    }
  • 401RFC 6749 5.2: invalid_client, also for a public client (introspection needs a client secret); carries WWW-Authenticate: Basic realm="stracker"
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "invalid_client",
      "error_description": "Client authentication failed"
    }
  • 429More than 30 requests a minute from one IP for one client; RFC 6749 temporarily_unavailable plus Retry-After
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }
  • 503RFC 6749 5.2: temporarily_unavailable, whether the token is live cannot be established right now; retry
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "temporarily_unavailable",
      "error_description": "The server cannot process the request right now; retry later"
    }

POST/v1/oauth/revoke

Revoke an OAuth access token or refresh token (RFC 7009)

  • Scope none (public document)

Form body token (+ optional token_type_hint, ignored when wrong, and client_id for a public client). A confidential client authenticates with Authorization: Basic base64(client_id:client_secret). Always answers 200 with {} once the client is authenticated, whether or not the token was live or belonged to the client (a token of another client is left alone). Revoking a refresh token revokes the whole grant; revoking an access token ends that token only.

Client authentication. Client authentication: client_secret_basic (Authorization: Basic base64(client_id:client_secret)), private_key_jwt (client_assertion_type + client_assertion, ES256 or RS256) or, for a public client, client_id alone.

Parameters

No parameters.

Request body application/x-www-form-urlencoded

FieldTypeDescription
tokenrequiredstringmin length 1 · max length 2048
token_type_hintstringmax length 64
client_idstringmin length 1 · max length 64
client_assertion_typestringmin length 1 · max length 128
client_assertionstringmin length 1 · max length 8192

Responses

  • 200The token is revoked, or there was nothing for this client to revoke
  • 400RFC 6749 5.2: invalid_request (not a form, token missing, a parameter repeated or unknown)
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "invalid_request",
      "error_description": "The request must be application/x-www-form-urlencoded"
    }
  • 401RFC 6749 5.2: invalid_client, the same answer for an unknown client, a wrong, revoked or expired secret or client assertion, and a disabled client; carries WWW-Authenticate: Basic realm="stracker"
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "invalid_client",
      "error_description": "Client authentication failed"
    }
  • 429More than 30 requests a minute from one IP for one client; RFC 6749 temporarily_unavailable plus Retry-After
    Example
    {
      "type": "https://stracker.io/errors/rate-limited",
      "title": "Too many requests",
      "status": 429,
      "detail": "Too many requests",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "RATE_LIMITED"
    }
  • 503RFC 6749 5.2: temporarily_unavailable, the revocation could not be recorded; retry
    FieldTypeDescription
    errorstringe.g. "invalid_client"
    error_descriptionstringe.g. "Client authentication failed"
    Example
    {
      "error": "temporarily_unavailable",
      "error_description": "The server cannot process the request right now; retry later"
    }

OAuth discovery

GET/.well-known/jwks.json

OAuth token signing keys (JWK Set)

  • Scope none (public document)

Public keys that verify OAuth access tokens: pending, active and retiring versions. Never private material. Cacheable for 10 minutes.

Parameters

No parameters.

Responses

  • 200The JWK Set
    FieldTypeDescription
    keysobject[]
    keys[].ktystringe.g. "EC"
    keys[].crvstringe.g. "P-256"
    keys[].xstring
    keys[].ystring
    keys[].kidstringe.g. "k_3f9a1c"
    keys[].algstringe.g. "ES256"
    keys[].usestringe.g. "sig"
  • 500
    Example
    {
      "type": "https://stracker.io/errors/internal-error",
      "title": "Internal server error",
      "status": 500,
      "detail": "Internal server error",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "INTERNAL_ERROR"
    }

GET/.well-known/oauth-authorization-server

OAuth authorization server metadata

  • Scope none (public document)

RFC 8414 metadata: authorization, token, revocation and introspection endpoints, JWKS URI, supported grant types (client_credentials, authorization_code, refresh_token), PKCE (S256), client authentication methods and scopes. Cacheable for 10 minutes.

Parameters

No parameters.

Responses

  • 200The authorization server metadata
    FieldTypeDescription
    issuerstringe.g. "https://api.stracker.vn"
    authorization_endpointstringe.g. "https://app.stracker.vn/oauth/authorize"
    token_endpointstringe.g. "https://api.stracker.vn/v1/oauth/token"
    jwks_uristringe.g. "https://api.stracker.vn/.well-known/jwks.json"
    grant_types_supportedstring[]
    response_types_supportedstring[]
    response_modes_supportedstring[]
    code_challenge_methods_supportedstring[]
    token_endpoint_auth_methods_supportedstring[]
    token_endpoint_auth_signing_alg_values_supportedstring[]Algorithms of a private_key_jwt assertion
    revocation_endpointstringe.g. "https://api.stracker.vn/v1/oauth/revoke"
    revocation_endpoint_auth_methods_supportedstring[]
    revocation_endpoint_auth_signing_alg_values_supportedstring[]
    introspection_endpointstringe.g. "https://api.stracker.vn/v1/oauth/introspect"
    introspection_endpoint_auth_methods_supportedstring[]
    introspection_endpoint_auth_signing_alg_values_supportedstring[]
    authorization_response_iss_parameter_supportedbooleane.g. true
    scopes_supportedstring[]
  • 500
    Example
    {
      "type": "https://stracker.io/errors/internal-error",
      "title": "Internal server error",
      "status": 500,
      "detail": "Internal server error",
      "instance": "/v1/…",
      "correlation_id": "b3f1c2b0-4b1a-4b1a-9e21-000000000000",
      "code": "INTERNAL_ERROR"
    }