Get drivers in viewport with automatic clustering based on zoom level.
Returns clusters for areas with many drivers and individual markers
for areas below the clustering threshold. The clustering behavior
adapts based on zoom level:
- Street view (zoom >= 17): Always show individual drivers
- City view (zoom <= 8): Cluster aggressively (> 2 drivers)
- Standard zoom: Cluster when > 5 drivers in a cell
# Arguments
* input.bounds - Viewport bounds (sw/ne corners)
* input.zoom - Map zoom level (1-20)
* input.online_status - Optional filter by Online or Busy
# Example
Explain whether a driver is eligible for a given service class.
Runs the same EligibilityEvaluator the dispatch path uses, so the
answer is authoritative — no chance of admin and dispatch
disagreeing. When the driver is ineligible, returns the structured
reasons so support can pinpoint the failing dimension.
# Authorization
Requires TenantAdmin or PlatformAdmin role.
The drivers drivers returns for the same input, as a CSV file:
every page at once, up to 5,000 rows. input.pagination is ignored.
truncated says when more matched than the file holds.
Email and phone are masked exactly as the list masks them.
# Authorization
Requires TenantAdmin or PlatformAdmin role. A staff seat needs both
Manage drivers and Export data; the owner needs no grant.
Get active taxi rides for the current user, scoped to the role
they're acting under for this request.
The same account can hold both Customer and Driver roles (common
in dev and for tenants where drivers also ride as passengers). If
we returned the union we'd leak the user's own passenger-side
dispatching order into the driver app, which then renders it as
an active trip and hides the actual ride-offer Accept UI. So we
scope by request_ctx.role.
The current driver's rides and earnings since since — for "today",
pass the driver's local midnight.
Covers the rides counted for the driver at or after since. A ride is
counted the moment it is settled, so it shows here as soon as it ends,
whichever day it was booked on.
Get nearby driver coordinates for map display.
Returns 5-20 nearby available drivers around a center point for UI visualization.
This is a lightweight query - it only returns driver IDs, coordinates, and ratings.
# Arguments
* input.center - Center coordinates to search from
* input.limit - Max drivers to return (5-20, default 10)
* input.radius_meters - Search radius in meters (default 5000m)
# Example
Get recent unique travel locations (pickup/dropoff addresses) from order history.
Returns locations deduplicated by coordinates, ordered by most recent usage.
Useful for showing users their frequently used addresses for quick selection.
# Arguments
* near - Where the passenger is now, or the pickup they chose. When
given, only places within 100 km of it are returned, so a trip taken
in another city is not offered here. Without it, every recent place.
* limit - Maximum number of unique locations to return (default: 5, max: 20)
# Example
Submitted taxi orders by pickup region and zone over the last 30 full UTC days.
Region totals include orders with no pickup zone; zone totals include
only orders assigned to that zone.
Get a single ride option pricing by ID.
# Authorization
Requires TenantAdmin role.
# Arguments
* id - Ride option pricing ID
* currency - Currency to display fee in (defaults to USD)
List ride option pricings with pagination and filtering.
# Authorization
Requires TenantAdmin role.
# Arguments
* input - Filter and pagination options
* currency - Currency to display fees in (defaults to USD)
The vehicle catalog by style, for the service-class form: one tab per
style, each vehicle with its map markers (white, black, amber) and
its card image (white livery).
A catalog vehicle painted in paint (#rrggbb), as a PNG data URL,
so the service-class form can show a colour before it is saved.
Rendered on demand and never stored; saving the class is what stores
its images. A style that cannot be painted comes back in its own
livery.
Public, unauthenticated live view of a shared trip, addressed by its
share token. Returns null for unknown, expired, or revoked tokens
alike (no enumeration signal). Intended to be polled by a logged-out
"follow my ride" web page.
The gateway must allow this query through without authentication and
rate-limit it by token/IP (tracked as the pre-prod gateway carve-out).
Get the current tenant's vehicle catalog config. Returns the
"show everything" defaults when no row exists yet — so callers
always get a non-null payload they can render straight into the
settings UI.
One vehicle colour, as the admin list shows it: the workspace's own or
a platform global, active or not. null when no such colour is
visible to the workspace.
# Authorization
Requires TenantAdmin role.
Get paginated list of active vehicle colors
Returns colors available for the tenant (tenant overrides + global colors).
Results are ordered by position.
One vehicle make, as the admin list shows it: the workspace's own or a
platform global, active or not. null when no such make is visible
to the workspace.
# Authorization
Requires TenantAdmin role.
One vehicle model, as the admin list shows it: the workspace's own or
a platform global, active or not. null when no such model is
visible to the workspace.
# Authorization
Requires TenantAdmin role.
Get paginated list of active vehicle models
Returns models available for the tenant (tenant overrides + global models).
Optionally filter by make_id.
Results are ordered by position.
The vehicle models among ids the workspace can see (its own and
platform globals, active or not), in catalog order. Ids that match no
visible model are left out. At most 500 ids per call.
# Authorization
Requires TenantAdmin role.
Read a booking request written in plain language and return the trip
it asks for: who, from where, to where, when and in what kind of
vehicle. Places are returned in the request's own words, to be looked
up with address search. Nothing is booked, quoted or stored.
For workspace admins, with the dispatcher copilot switched on under
Settings → AI. A mutation because each call spends on the
workspace's AI provider.
Errors carry a code: AI_NOT_ENABLED when the feature is off,
AI_CALL_FAILED when the provider could not be reached or refused,
AI_PARSE_FAILED when its answer could not be used, INVALID_INPUT
for an empty or over-long request or an unknown time zone, and
UNAUTHORIZED for a caller who is not an admin.
Manually assign a driver to an order.
# Authorization
Requires TenantAdmin or PlatformAdmin role.
# Arguments
* input - The driver assignment input containing orderId, driverId, and optional force flag
# Returns
The assignment response containing success status, updated order, and optional message.
# Errors
- Unauthorized: If caller is not an admin
- NotFound: If order or driver does not exist
- InvalidState: If order is not in a dispatchable state or driver is not approved
- InvalidState: If order already has a driver and force=false
Swap the payment method used for an active taxi order.
Allowed any time before the payment for the order is captured (i.e.
from booking through end-of-ride payment confirmation). The new method
is authorized / debited first; only on success is the previous method
voided or refunded.
# Errors
- INVALID_INPUT — missing/extra payment_method_id for the chosen type.
- INVALID_STATE — order is in a terminal state, already captured, or the
new method needs 3DS verification (not supported in swap flow today).
- PAYMENT_FAILED — PSP declined the new method.
- UNAUTHORIZED — caller is not the order owner.
Confirm the metered fare submitted by driver.
Called by passenger after reviewing the driver-submitted fare.
Once confirmed, payment is captured and the ride is completed.
Mint (or re-fetch) a public "follow my ride" link for one of the
caller's own active trips. Returns a stable link if one is already
active for the trip.
Let this driver work without KYC, deliberately and on the record.
Before waivers existed an operator achieved the same thing by flipping
the driver to Approved, which left nothing saying who allowed it, why,
or for how long. expires_at of None means indefinite.
# Authorization
Requires TenantAdmin, TenantOwner or PlatformAdmin.
Read what a rider typed or said ("to the airport at 6 tomorrow, a big
car") and return the trip it asks for. Places are returned in the
rider's own words, to be looked up with address search. Nothing is
booked, quoted or stored.
For a signed-in account, with the ride booking assistant switched on
under Settings → AI. Each account may ask 10 times in 10 minutes, and
a request may be 500 characters long.
Errors carry a code: UNAUTHENTICATED without a session,
AI_NOT_ENABLED when the feature is off, RATE_LIMITED (with
retryAfterSecs) when the account has asked too often,
AI_CALL_FAILED or AI_PARSE_FAILED when the request could not be
read, and INVALID_INPUT for an empty or over-long request or an
unknown time zone. The message never names the provider or says why
it failed.
Raise an SOS during an active trip. Emits a realtime safety alert and
opens a maximum-priority support ticket for ops triage. Returns the
ticket reference so the rider sees confirmation help is on the way.
The driver's app asks for a new route after the driver has left the
one they were following.
The app follows the route on the phone and knows first when a turn was
missed. Whether a route is then asked of a routing provider is decided
here, against the ride's reroute budget, so a refusal is an ordinary
answer and not an error: the app keeps the route it has and, when told
to, asks again later.
Withdraw a waiver. The driver falls back to needing real KYC to go
online; they are not forced offline mid-shift, but cannot come back on
without it.
# Authorization
Requires TenantAdmin, TenantOwner or PlatformAdmin.
Set driver status to offline (unavailable for orders)
This mutation:
- Sets the driver as unavailable
- Removes driver info from Redis cache (demotes from online pool)
Set driver status to online (available for orders)
This mutation:
- Validates that the driver is approved
- Infers the zone from the provided coordinates
- Updates the driver's location
- Sets the driver as available
- Promotes driver info to Redis cache for quick dispatch
Enable or disable one of the service classes the driver qualifies for.
Disabling a class removes the driver from dispatch for it end-to-end:
they stop receiving offers for it immediately while online, and are not
indexed for it on their next go-online. Re-enabling restores it (subject
to the driver still qualifying). In-flight offers/trips are unaffected.
Returns the driver's refreshed manageable classes, each with its current
on/off state.
Set the service classes for a driver.
Replaces all existing service class assignments with the provided list.
Pass an empty array to remove all service class assignments.
# Authorization
Requires TenantAdmin or PlatformAdmin role.
Set or clear a single (driver, service class) eligibility override.
INCLUDE forces the driver eligible regardless of dynamic criteria.
EXCLUDE forces the driver ineligible regardless of dynamic criteria.
CLEAR removes any existing override; eligibility falls back to
pure criteria evaluation (or to manual-roster check on Manual
classes).
Note: this only persists the override row. The driver's currently
cached eligible-set updates next time they go online; for an
immediate effect, an admin can also force-offline the driver.
# Authorization
Requires TenantAdmin or PlatformAdmin role.
Toggle a driver's VIP-class eligibility. Default is true for all
drivers; admins flip to false to exclude a specific driver from
VIP-tier dispatch (without revoking the qualifying ratings/vehicle).
Requires TenantAdmin or PlatformAdmin role.
A courier on a delivery round leaves a shop without its order: the
shop is shut, or has nothing to hand over. The round goes on for the
other shops; this one and the customer are told nobody is coming for
that part.
Only at the stop the courier has arrived at, and not for the last
shop left on the round — with nothing to carry, cancel the delivery.
Submit vehicle details during driver onboarding
This mutation:
- Validates that the driver is in Pending status
- Validates that the vehicle model and color exist
- Updates the driver's vehicle information
- Changes driver status to PendingReview for admin approval
After calling this mutation, the driver must wait for admin approval
before they can start accepting rides.
Propose changes to how ride requests are offered to drivers, from a
short description of the situation. Nothing is saved: the answer is
the baseline profile's settings, the same settings with the proposed
changes, and a reason for each. An accepted proposal becomes a new
profile (createDispatchProfile, which starts with no traffic)
holding proposed (updateDispatchProfile).
Only a fixed list of settings can be proposed (DispatchSettingKey),
each inside a range; per-tier policy and anything else is carried
over untouched.
For the admins who may edit dispatch settings, with the setup
assistant switched on under Settings → AI. Errors carry the same
codes as suggestServiceClasses, and NOT_FOUND for a workspace
with no dispatch settings to start from.
Propose service classes the workspace is missing, from a short
description of the operation. Nothing is created: each suggestion is
a name, a capacity and a fare for an admin to accept, and an accepted
one is created with createServiceClass, inactive.
For the admins who may edit pricing, with the setup assistant
switched on under Settings → AI. A mutation because each call spends
on the workspace's AI provider.
Errors carry a code: AI_NOT_ENABLED when the feature is off,
AI_CALL_FAILED when the provider could not be reached or refused,
AI_PARSE_FAILED when its answer could not be used, and
INVALID_INPUT for an empty or over-long description.
Update driver's GPS location while online
This mutation:
- Updates driver's GPS coordinates in Redis cache
- Recalculates H3 geospatial indexes if location changed significantly
- Updates zone in PostgreSQL if driver moved to a different zone
- Does NOT update PostgreSQL on every location ping (only Redis for performance)
Update the wait/stopover time for an active taxi order.
Recalculates the stopover fee based on the service class per-minute rate
and updates the order total accordingly. Only the order's rider or an
admin-tier session may; anyone else gets NOT_FOUND.
Retired. Drivers no longer set a personal search radius — the tenant's
dispatch config alone decides how far an order reaches. Kept as a no-op
so published driver apps that still call it get a success back.
Deprecation reason: No-op. Drivers no longer have a personal search radius; the dispatch config alone decides reach. Retire after published app release floors permit it; BET-222.
Update the three include-globals toggles. Preserves any per-row
hidden globals already set — switching the toggle off doesn't
erase the cherry-picked suppressions.
Subscribe to driver events (Taxi service)
Receive real-time events relevant to taxi drivers:
- New ride offers dispatched to you
- Ride acceptance confirmations
- Trip lifecycle events (start, complete, cancel)
- Chat messages from passengers
- Earnings updates
- Notifications
**Requirements:**
- Must be authenticated
- Must have Driver role
- Must be using Taxi app
Example:
graphqlsubscription {
driverEvents {
__typename
... on RideOfferEvent {
orderId
pickupAddress
fare
expiresAt
}
... on TripStartedEvent {
orderId
startedAt
}
}
}