Access

Taps, presence and credentials — the gate rail. One `tap` write serves a school gate and a stadium door.

47 endpoints

GET /v3/band #

bearer driver_app beneficiary_app pass_app pass_web admin_web device credential

Query parameters

Name	Type		Constraints
`status`	string \| null	optional	`in_stock` `assigned` `active` `suspended` `lost` `damaged` `retired`
`school`	string \| null	optional	—
`q`	string \| null	optional	max length 100
`batch`	string \| null	optional	max length 50
`color`	string \| null	optional	max length 50

Response

Returns { "data": [BandRow] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`type`	string \| null	required	—
`band_type`	any	required	—
`status`	string	required	—
`event_id`	string \| null	required	—
`wearer`	string \| null	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`school_id`	string \| null	required	—
`school_name`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`created_at`	string (date-time)	required	—

POST /v3/band #

bearer driver_app beneficiary_app admin_web pass_web access.band_manage device credential

Request body

Field	Type		Constraints
`serial_number`	string	required	max length 64
`earth_code`	string \| null	optional	max length 32
`batch_number`	string \| null	optional	max length 64
`color`	string \| null	optional	max length 32
`band_type_id`	string \| null	optional	—
`school_id`	string (uuid)	optional	—
`expires_at`	string \| null	optional	—

Response

Returns { "data": BandWrite }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`event_id`	string \| null	required	—

GET /v3/band-type #

bearer driver_app beneficiary_app pass_app pass_web admin_web device credential

Query parameters

Name	Type		Constraints
`school`	string \| null	optional	—

Response

Returns { "data": [BandType] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—

POST /v3/band/assign #

bearer driver_app beneficiary_app pass_app admin_web access.band_manage device credential

Request body

Field	Type		Constraints
`serial_number`	string	required	max length 64
`student_id`	string \| null	optional	—
`account_id`	string \| null	optional	—
`wallet_id`	string \| null	optional	—

Response

Returns { "data": BandWrite }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`event_id`	string \| null	required	—

POST /v3/band/bulk #

bearer driver_app beneficiary_app admin_web pass_web access.band_manage device credential

A factory shipment, in one call.

Answers per serial rather than with a count, because the operator is holding the spreadsheet the list came from and needs to know WHICH rows to look at. Re-sending the same list is safe: every serial comes back duplicate, nothing 409s, and the shipment is not half-registered.

Request body

Field	Type		Constraints
`serial_numbers`	string \| null[]	required	min items 1 · max items 2000
`batch_number`	string \| null	optional	max length 64
`color`	string \| null	optional	max length 32
`band_type_id`	string \| null	optional	—
`school_id`	string (uuid)	optional	—
`event_id`	string \| null	optional	—
`expires_at`	string \| null	optional	—

Response

Returns { "data": BandBulkIntake }.

Field	Type		Constraints
`registered`	integer	required	—
`duplicate`	integer	required	—
`invalid`	integer	required	—
`results`	object[]	required	—

GET /v3/band/{serial} #

bearer driver_app beneficiary_app pass_app pass_web admin_web device credential

Path parameters

Name	Type	Notes
`serial`	string

Response

Returns { "data": BandDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`tags`	object[]	required	—
`wearer`	any	required	—
`wallet`	any	required	—

POST /v3/band/{serial}/replace #

bearer driver_app beneficiary_app pass_app admin_web access.band_manage device credential

a dead wristband swapped for a live one (Cloud9 3).

The wearer and their wallet come off the band being replaced, never off the request: naming them would let a caller point the balance at somebody else. One transaction, so a failure leaves the guest with the working band they already had rather than two dead ones and a balance they cannot spend.

Path parameters

Name	Type	Notes
`serial`	string

Request body

Field	Type		Constraints
`serial_number`	string	required	max length 64
`reason`	string	required	`lost` `damaged`

Response

Returns { "data": BandWrite }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`event_id`	string \| null	required	—

POST /v3/band/{serial}/status #

bearer driver_app beneficiary_app pass_app admin_web access.band_manage device credential

Path parameters

Name	Type	Notes
`serial`	string

Request body

Field	Type		Constraints
`status`	string	required	`in_stock` `assigned` `active` `suspended` `lost` `damaged` `retired`

Response

Returns { "data": BandWrite }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`event_id`	string \| null	required	—

POST /v3/device/heartbeat #

bearer driver_app beneficiary_app pass_app device credential

Request body

Field	Type		Constraints
`serial_number`	string	required	max length 64
`battery_pct`	integer \| null	optional	min 0 · max 100
`signal_strength`	integer \| null	optional	min 0 · max 10
`firmware`	string \| null	optional	max length 64
`data_used_bytes`	integer \| null	optional	min 0
`sim_present`	boolean \| null	optional	—
`recorded_at`	string (date-time)	required	—

Response

Returns { "data": HeartbeatAck }.

Field	Type		Constraints
`ok`	boolean	required	—
`presence`	string	required	`online` `low_battery`
`next_heartbeat_seconds`	integer	required	—

POST /v3/portal/band-type #

bearer admin_web access.band_manage device credential

Request body

Field	Type		Constraints
`name`	string	required	max length 80
`school_id`	string (uuid)	optional	—

Response

Returns { "data": BandType }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—

DELETE /v3/portal/band-type/{id} #

bearer admin_web access.band_manage device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

PATCH /v3/portal/band-type/{id} #

bearer admin_web access.band_manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`name`	string	required	max length 80

Response

Returns { "data": BandType }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—

PATCH /v3/portal/band/{id} #

bearer admin_web access.band_manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`band_type_id`	string \| null	optional	—
`school_id`	string (uuid)	optional	—
`status`	string	optional	`in_stock` `assigned` `active` `suspended` `lost` `damaged` `retired`

Response

Returns { "data": BandEdited }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`school_id`	string \| null	required	—
`school_name`	string \| null	required	—

POST /v3/portal/band/{serial}/school #

bearer admin_web access.band_manage device credential

Path parameters

Name	Type	Notes
`serial`	string

Request body

Field	Type		Constraints
`school_id`	string (uuid)	required	—

Response

Returns { "data": BandAssignedToSchool }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`serial_number`	string	required	—
`earth_code`	string \| null	required	—
`batch_number`	string \| null	required	—
`color`	string \| null	required	—
`band_type_id`	string \| null	required	—
`status`	string	required	—
`student_id`	string \| null	required	—
`account_id`	string \| null	required	—
`wallet_id`	string \| null	required	—
`assigned_at`	string \| null	required	—
`expires_at`	string \| null	required	—
`tags`	object[]	required	—
`wearer`	any	required	—
`wallet`	any	required	—
`school_id`	string (uuid)	required	—
`school_name`	string	required	—

GET /v3/portal/device #

bearer admin_web device credential

Query parameters

Name	Type		Constraints
`status`	string \| null	optional	`provisioned` `approved` `maintenance` `retired` `blocked`
`kind`	string \| null	optional	`scanner` `onboard_unit` `pos` `gate`
`zone_id`	string \| null	optional	—
`q`	string \| null	optional	max length 120
`school`	string \| null	optional	—
`batch_number`	string \| null	optional	max length 64
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [WebDevice] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string \| null	required	—
`serial_number`	string	required	—
`batch_number`	string \| null	required	—
`kind`	string	required	—
`status`	string	required	—
`zone`	any	required	—
`school`	any	required	—
`imei`	string \| null	required	—
`sim_msisdn`	string \| null	required	—
`sim_present`	boolean \| null	required	—
`battery_pct`	integer \| null	required	—
`signal_strength`	integer \| null	required	—
`firmware`	string \| null	required	—
`data_used_bytes`	integer \| null	required	—
`presence`	string	required	—
`last_seen_at`	string \| null	required	—
`row_version`	integer	required	—

POST /v3/portal/device #

bearer admin_web access.device_manage device credential

Request body

Field	Type		Constraints
`name`	string	required	max length 120
`serial_number`	string	required	max length 64
`kind`	string \| null	optional	`scanner` `onboard_unit` `pos` `gate` `mobile` `browser`
`zone_id`	string \| null	optional	—
`school_id`	string \| null	optional	—
`imei`	string \| null	optional	max length 32
`sim_msisdn`	string \| null	optional	max length 20
`firmware`	string \| null	optional	max length 64
`batch_number`	string \| null	optional	max length 80

Response

Returns { "data": WebDevice }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string \| null	required	—
`serial_number`	string	required	—
`batch_number`	string \| null	required	—
`kind`	string	required	—
`status`	string	required	—
`zone`	any	required	—
`school`	any	required	—
`imei`	string \| null	required	—
`sim_msisdn`	string \| null	required	—
`sim_present`	boolean \| null	required	—
`battery_pct`	integer \| null	required	—
`signal_strength`	integer \| null	required	—
`firmware`	string \| null	required	—
`data_used_bytes`	integer \| null	required	—
`presence`	string	required	—
`last_seen_at`	string \| null	required	—
`row_version`	integer	required	—

GET /v3/portal/device/batch-numbers #

bearer admin_web device credential

Response

An array of string.

PATCH /v3/portal/device/bulk/school #

bearer admin_web access.device_manage device credential

Request body

Field	Type		Constraints
`device_ids`	string (uuid)[]	required	min items 1 · max items 500
`school_id`	string (uuid)	required	—

Response

Returns { "data": [WebDevice] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string \| null	required	—
`serial_number`	string	required	—
`batch_number`	string \| null	required	—
`kind`	string	required	—
`status`	string	required	—
`zone`	any	required	—
`school`	any	required	—
`imei`	string \| null	required	—
`sim_msisdn`	string \| null	required	—
`sim_present`	boolean \| null	required	—
`battery_pct`	integer \| null	required	—
`signal_strength`	integer \| null	required	—
`firmware`	string \| null	required	—
`data_used_bytes`	integer \| null	required	—
`presence`	string	required	—
`last_seen_at`	string \| null	required	—
`row_version`	integer	required	—

GET /v3/portal/device/stats #

bearer admin_web device credential

Response

Returns { "data": WebDeviceStats }.

Field	Type		Constraints
`total_wearables`	integer	required	—
`wearables_assigned`	integer	required	—
`total_scanners`	integer	required	—
`scanners_assigned`	integer	required	—

PATCH /v3/portal/device/{id} #

bearer admin_web access.device_manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`update_mask`	string[]	required	min items 1 · max items 7
`expected_row_version`	integer	required	min 1
`name`	string \| null	optional	max length 120
`kind`	string \| null	optional	`scanner` `onboard_unit` `pos` `gate` `mobile` `browser`
`status`	string \| null	optional	`provisioned` `approved` `maintenance` `retired` `blocked`
`zone_id`	string \| null	optional	—
`imei`	string \| null	optional	max length 32
`sim_msisdn`	string \| null	optional	max length 20
`firmware`	string \| null	optional	max length 64

Response

Returns { "data": WebDevice }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string \| null	required	—
`serial_number`	string	required	—
`batch_number`	string \| null	required	—
`kind`	string	required	—
`status`	string	required	—
`zone`	any	required	—
`school`	any	required	—
`imei`	string \| null	required	—
`sim_msisdn`	string \| null	required	—
`sim_present`	boolean \| null	required	—
`battery_pct`	integer \| null	required	—
`signal_strength`	integer \| null	required	—
`firmware`	string \| null	required	—
`data_used_bytes`	integer \| null	required	—
`presence`	string	required	—
`last_seen_at`	string \| null	required	—
`row_version`	integer	required	—

POST /v3/portal/device/{id}/airtime #

bearer admin_web money.adjust device idempotency credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`amount_minor`	integer	required	min 1 · max 100000000
`currency`	string	required	min length 3 · max length 3

Response

Returns { "data": … }; this endpoint's payload is not yet pinned to a named shape.

GET /v3/portal/device/{id}/history #

bearer admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Query parameters

Name	Type		Constraints
`from`	string	required	—
`to`	string	required	—
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [DeviceHistoryEntry] }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	required	—
`changes`	object	required	—
`actor_user_id`	string \| null	required	—
`at`	string (date-time)	required	—

PATCH /v3/portal/device/{id}/school #

bearer admin_web access.device_manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`school_id`	string (uuid)	required	—

Response

Returns { "data": WebDevice }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string \| null	required	—
`serial_number`	string	required	—
`batch_number`	string \| null	required	—
`kind`	string	required	—
`status`	string	required	—
`zone`	any	required	—
`school`	any	required	—
`imei`	string \| null	required	—
`sim_msisdn`	string \| null	required	—
`sim_present`	boolean \| null	required	—
`battery_pct`	integer \| null	required	—
`signal_strength`	integer \| null	required	—
`firmware`	string \| null	required	—
`data_used_bytes`	integer \| null	required	—
`presence`	string	required	—
`last_seen_at`	string \| null	required	—
`row_version`	integer	required	—

POST /v3/portal/pickup/confirm #

bearer admin_web access.tap_manual device credential

Request body

Field	Type		Constraints
`code`	string	required	min length 4 · max length 12
`student_id`	string (uuid)	required	—
`zone_id`	string \| null	optional	—
`outcome`	string \| null	optional	`released` `declined`

Response

Returns { "data": Ack }.

Field	Type		Constraints
`ok`	boolean	required	—

POST /v3/portal/pickup/validate #

bearer admin_web access.tap_manual device credential

Request body

Field	Type		Constraints
`code`	string	required	min length 4 · max length 12

Response

Returns { "data": PickupValidation }.

Field	Type		Constraints
`student`	object	required	—
`student.id`	string (uuid)	required	—
`student.name`	string	required	—
`student.grade`	string \| null	required	—
`student.photo`	any	required	—
`guardian`	object	required	—
`guardian.account_id`	string (uuid)	required	—
`guardian.name`	string	required	—
`guardian.phone`	string \| null	required	—
`guardian.relationship`	string \| null	required	—

GET /v3/portal/zone #

bearer admin_web device credential

Query parameters

Name	Type		Constraints
`kind`	string \| null	optional	`school` `gate` `bus` `canteen` `library` `office` `event` `other` +2 more
`exclude_kind`	string \| null	optional	`school` `gate` `bus` `canteen` `library` `office` `event` `other` +2 more
`q`	string \| null	optional	max length 120
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [WebZone] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`parent_zone_id`	string \| null	required	—
`name`	string	required	—
`kind`	string	required	—
`status`	string	required	—
`description`	string \| null	required	—
`metadata`	object	required	—
`centroid`	any	required	—
`geofence_radius_m`	integer \| null	required	—
`occupancy`	integer	required	—
`assignees`	object[]	required	—
`charges`	object[]	required	—
`vehicle`	any	required	—
`row_version`	integer	required	—

POST /v3/portal/zone #

bearer admin_web settings.manage device credential

Request body

Field	Type		Constraints
`name`	string	required	max length 120
`kind`	string \| null	optional	`school` `gate` `bus` `canteen` `library` `office` `cocurricular` `other`
`description`	string \| null	optional	max length 300
`parent_zone_id`	string \| null	optional	—
`centroid_lat`	number \| null	optional	min -90 · max 90
`centroid_lng`	number \| null	optional	min -180 · max 180
`geofence_radius_m`	integer \| null	optional	min 10 · max 10000
`metadata`	array \| null	optional	max items 20

Response

Returns { "data": WebZone }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`parent_zone_id`	string \| null	required	—
`name`	string	required	—
`kind`	string	required	—
`status`	string	required	—
`description`	string \| null	required	—
`metadata`	object	required	—
`centroid`	any	required	—
`geofence_radius_m`	integer \| null	required	—
`occupancy`	integer	required	—
`assignees`	object[]	required	—
`charges`	object[]	required	—
`vehicle`	any	required	—
`row_version`	integer	required	—

PATCH /v3/portal/zone/{id} #

bearer admin_web settings.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`update_mask`	string[]	required	min items 1 · max items 9
`expected_row_version`	integer	required	min 1
`name`	string \| null	optional	max length 120
`kind`	string \| null	optional	`school` `gate` `bus` `canteen` `library` `office` `event` `other` +2 more
`status`	string \| null	optional	`active` `suspended` `archived`
`description`	string \| null	optional	max length 300
`parent_zone_id`	string \| null	optional	—
`centroid_lat`	number \| null	optional	min -90 · max 90
`centroid_lng`	number \| null	optional	min -180 · max 180
`geofence_radius_m`	integer \| null	optional	min 10 · max 10000
`metadata`	array \| null	optional	max items 20

Response

Returns { "data": WebZone }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`parent_zone_id`	string \| null	required	—
`name`	string	required	—
`kind`	string	required	—
`status`	string	required	—
`description`	string \| null	required	—
`metadata`	object	required	—
`centroid`	any	required	—
`geofence_radius_m`	integer \| null	required	—
`occupancy`	integer	required	—
`assignees`	object[]	required	—
`charges`	object[]	required	—
`vehicle`	any	required	—
`row_version`	integer	required	—

PUT /v3/portal/zone/{id}/access-mode #

bearer admin_web settings.manage device credential

the explicit open|rostered flip (admin judgment; reach.md §3.4).

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`access_mode`	string	required	`open` `rostered`

Response

Returns { "data": AccessModeSet }.

Field	Type		Constraints
`zone_id`	string (uuid)	required	—
`access_mode`	string	required	—

GET /v3/portal/zone/{id}/profile #

bearer admin_web device credential

The location profile (SP-8, terra-api §11.7): meal periods + the priced menu as ONE document-shaped read over TYPED rows (0090). The projections and writes live ON the models (databases are classes) — this controller only orchestrates.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": ZoneProfile }.

Field	Type		Constraints
`periods`	object[]	required	—
`menu_items`	object[]	required	—

PUT /v3/portal/zone/{id}/profile #

bearer admin_web settings.manage device credential

PUT replaces each PROVIDED collection wholesale — the config card saves the whole form; an omitted collection is untouched.

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`periods`	object[]	optional	max items 12
`menu_items`	object[]	optional	max items 200

Response

Returns { "data": ZoneProfile }.

Field	Type		Constraints
`periods`	object[]	required	—
`menu_items`	object[]	required	—

GET /v3/portal/zone/{id}/roster #

bearer admin_web device credential

the zone's members (provenance visible) + rules + mode.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": WebRoster }.

Field	Type		Constraints
`zone_id`	string (uuid)	required	—
`access_mode`	string	required	—
`members`	object[]	required	—
`rules`	object[]	required	—

POST /v3/portal/zone/{id}/roster/member #

bearer admin_web settings.manage device credential

a hand-picked member (via='manual').

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`student_id`	string (uuid)	optional	—
`account_id`	string (uuid)	optional	—

Response

Returns { "data": Written }.

Field	Type		Constraints
`id`	string (uuid)	required	—

DELETE /v3/portal/zone/{id}/roster/member/{memberId} #

bearer admin_web settings.manage device credential

manual members only (rule rows belong to their rule).

Path parameters

Name	Type	Notes
`id`	string
`memberId`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

POST /v3/portal/zone/{id}/roster/rule #

bearer admin_web settings.manage device credential

label-based auto-enrollment; the projector materializes.

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`tag_ids`	string (uuid)[]	required	min items 1 · max items 8

Response

Returns { "data": … }; this endpoint's payload is not yet pinned to a named shape.

DELETE /v3/portal/zone/{id}/roster/rule/{ruleId} #

bearer admin_web settings.manage device credential

its members cascade; the projector re-covers survivors.

Path parameters

Name	Type	Notes
`id`	string
`ruleId`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

GET /v3/portal/zone/{id}/service-log #

bearer admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Query parameters

Name	Type		Constraints
`kind`	string \| null	optional	`fuel` `maintenance`
`from`	string \| null	optional	—
`to`	string \| null	optional	—
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [ServiceLog] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	required	—
`occurred_on`	string \| null	required	—
`amount_minor`	integer \| null	required	—
`currency`	string \| null	required	—
`quantity_liters`	number \| null	required	—
`odometer_km`	integer \| null	required	—
`description`	string \| null	required	—

POST /v3/portal/zone/{id}/service-log #

bearer admin_web transport.plan device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`kind`	string	required	`fuel` `maintenance`
`occurred_on`	string	required	—
`amount_minor`	integer \| null	optional	min 0 · max -9223372036854775808
`currency`	string \| null	optional	min length 3 · max length 3
`quantity_liters`	number \| null	optional	min 0 · max 99999
`odometer_km`	integer \| null	optional	min 0
`description`	string \| null	optional	max length 500
`metadata`	array \| null	optional	max items 20

Response

Returns { "data": ServiceLog }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	required	—
`occurred_on`	string \| null	required	—
`amount_minor`	integer \| null	required	—
`currency`	string \| null	required	—
`quantity_liters`	number \| null	required	—
`odometer_km`	integer \| null	required	—
`description`	string \| null	required	—

DELETE /v3/portal/zone/{id}/service-log/{logId} #

bearer admin_web transport.plan device credential

Path parameters

Name	Type	Notes
`id`	string
`logId`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

PATCH /v3/portal/zone/{id}/service-log/{logId} #

bearer admin_web transport.plan device credential

Path parameters

Name	Type	Notes
`id`	string
`logId`	string

Request body

Field	Type		Constraints
`update_mask`	string[]	required	min items 1 · max items 8
`kind`	string \| null	optional	`fuel` `maintenance`
`occurred_on`	string \| null	optional	—
`amount_minor`	integer \| null	optional	min 0 · max -9223372036854775808
`currency`	string \| null	optional	min length 3 · max length 3
`quantity_liters`	number \| null	optional	min 0 · max 99999
`odometer_km`	integer \| null	optional	min 0
`description`	string \| null	optional	max length 500
`metadata`	array \| null	optional	max items 20

Response

Returns { "data": ServiceLog }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	required	—
`occurred_on`	string \| null	required	—
`amount_minor`	integer \| null	required	—
`currency`	string \| null	required	—
`quantity_liters`	number \| null	required	—
`odometer_km`	integer \| null	required	—
`description`	string \| null	required	—

PUT /v3/portal/zone/{id}/vehicle #

bearer admin_web settings.manage device credential

The real fleet record (0115) — capacity/fuel_type/fuel_consumption live on `vehicles`, not zones.metadata. Required the first time (a new bus), partial-edit-friendly after that (WebVehicleService).

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`capacity`	integer \| null	optional	min 1 · max 999
`fuel_type`	string \| null	optional	`petrol` `diesel` `electric` `hybrid`
`fuel_consumption_km_per_l`	number \| null	optional	min 3 · max 12

Response

Returns { "data": VehicleFields }.

Field	Type		Constraints
`zone_id`	string (uuid)	required	—
`capacity`	integer \| null	required	—
`fuel_type`	string \| null	required	—
`fuel_consumption_km_per_l`	number \| null	required	—

GET /v3/presence #

bearer beneficiary_app parent_app device credential

Query parameters

Name	Type		Constraints
`students`	string	required	max length 8000

Response

Returns { "data": [PresenceEntry] } with meta.next_cursor for the next page.

Field	Type		Constraints
`student_id`	string	required	—
`state`	string	required	`present` `away` `none`
`path`	object[]	optional	—
`since`	string \| null	optional	—
`last_zone`	object	optional	—
`last_zone.id`	string	required	—
`last_zone.name`	string \| null	optional	—
`last_seen`	string \| null	optional	—

POST /v3/student/{id}/pickup-code #

bearer beneficiary_app parent_app admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`account_id`	string \| null	optional	—

Response

Returns { "data": PickupCodeMinted }.

Field	Type		Constraints
`code`	string	required	—
`expires_at`	string (date-time)	required	—

POST /v3/tap #

bearer driver_app beneficiary_app pass_app device credential

Request body

Field	Type		Constraints
`client_event_id`	string (uuid)	required	—
`zone_id`	string (uuid)	required	—
`device_id`	string \| null	optional	—
`band_serial`	string \| null	optional	max length 64
`student_id`	string \| null	optional	—
`direction`	string	required	`check_in` `check_out`
`method`	string	required	`nfc` `manual` `qr`
`occurred_at`	string (date-time)	required	—
`pickup_code`	string \| null	optional	max length 10

Response

Returns { "data": TapVerdict }.

Field	Type		Constraints
`result`	string	required	`allowed` `denied` `noop`
`reason`	string	optional	—
`detail`	string	optional	—
`holder`	string	optional	—
`admits`	string[]	optional	—
`charge`	object	optional	—
`charge.transaction_id`	string (uuid)	required	—
`charge.amount`	object	required	—
`charge.balance_after`	object	required	—

POST /v3/tap/batch #

bearer driver_app beneficiary_app pass_app device credential gzip

Offline outbox drain: PER-ITEM results — one poisoned item never sinks the batch (§7.3). The cap is `terra.batch.max_items`, the same number bootstrap advertises to the apps. Items process sequentially (each tap is its own transaction), so a max-size reconnect drain is bounded by a TIME BUDGET instead of item count: past the budget the loop stops and the response carries only the processed prefix — an omitted item has no result, which the app's drain already reads as "keep & retry next cycle". Worst-case latency is capped; no tap is ever dropped.

Items are applied in occurred_at ORDER, not the order the array happened to arrive in (0136). Presence is a fold over a sequence, so applying a check-out before the check-in it follows leaves the holder inside forever — and the array order is whatever the handset's outbox produced after its own retries, which is not a guarantee anybody made. Sorting is one usort and removes the whole class.

The time budget then truncates the LATEST taps rather than an arbitrary suffix, which is the right half to re-drain: the oldest facts land first and the newest come back next cycle.

The REPLY still comes back in the order the caller sent, though. Applying in time order is ours to decide; re-ordering somebody's array under them is not, and a client lining results up by position would silently read the wrong verdict against the wrong tap. Results are collected against each item's original index and sorted back before they go out.

Headers

Header		Notes
`Content-Encoding`	optional	Optional request-body compression; compressed cap 1 MB, decompressed cap 10 MB.

Request body

Field	Type		Constraints
`taps`	array	required	min items 1 · max items 500

Response

Returns { "data": TapBatch }.

Field	Type		Constraints
`results`	TapBatchItem[]	required	—

POST /v3/tap/{event}/undo #

bearer driver_app beneficiary_app pass_app admin_web access.undo device credential

reverse a mis-tap by its access-event id. Idempotent by construction — a replay returns the same compensating facts.

Path parameters

Name	Type	Notes
`event`	string

Response

Returns { "data": … }; this endpoint's payload is not yet pinned to a named shape.

GET /v3/zone/{id}/occupancy #

bearer driver_app beneficiary_app pass_app pass_web admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Occupancy }.

Field	Type		Constraints
`zone_id`	string (uuid)	required	—
`name`	string	required	—
`container`	object	required	—
`container.id`	string (uuid)	required	—
`container.name`	string	required	—
`open_sessions`	integer	required	—
`as_of`	string	required	—