{ "openapi": "3.1.0", "info": { "title": "Hire A Bus operator API", "version": "1.0.0", "description": "The Hire A Bus operator API. It serves the operator and driver mobile\napp, and third-party dispatch and fleet systems, over the same\nendpoints and the same bearer credential.\n\nAuthenticate with `Authorization: Bearer `. A token carries\nexplicit abilities (`jobs:read`, `quotes:write`, `bookings:read`,\n`drivers:read`, `drivers:write`, `payouts:read`, `webhooks:manage`);\na call needing an ability the token does not hold is refused with\n`403 missing_ability`, and a token with no abilities can do nothing.\n\nMoney is always an integer in the currency's minor units, beside the\n`currency_code` it belongs to. Requests that create or settle\nsomething take an `Idempotency-Key` header; replaying one returns the\noriginal response rather than repeating the work.\n\nJobs are pre-deposit work: they carry the itinerary an operator needs\nin order to price the job, and nothing that identifies the customer.\nCustomer contact details appear on a booking, once it is won." }, "servers": [ { "url": "https://hireabus.com", "description": "Production" } ], "paths": { "/api/v1/auth/devices": { "get": { "operationId": "v1.auth.devices", "description": "Scoped to the tokenable behind the presented credential — never to an\nid from the request — so one user cannot enumerate another's devices.", "summary": "The signed-in devices for the calling operator user", "tags": [ "Auth" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "device_name": { "type": "string" }, "current": { "type": "boolean" }, "last_used_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "device_name", "current", "last_used_at", "expires_at", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/api/v1/auth/devices/{id}": { "delete": { "operationId": "v1.auth.devices.revoke", "summary": "Sign a device out. Takes effect on that device's very next call", "tags": [ "Auth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/api/v1/auth/exchange": { "post": { "operationId": "v1.auth.exchange", "description": "The raw token is returned exactly once, in this response. It is stored\nhashed and cannot be read back from anywhere afterwards.", "summary": "Exchange a consumed sign-in link for a bearer token", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 200 }, "device_name": { "type": [ "string", "null" ], "maxLength": 60 } }, "required": [ "token" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "token_id": { "type": "string" }, "device_name": { "type": "string" }, "abilities": { "type": "array", "items": {} }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "token", "token_id", "device_name", "abilities", "expires_at" ] } }, "required": [ "data" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "invalid_sign_in_link" }, "message": { "type": "string", "const": "That sign-in link has expired or has already been used. Request a new one." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/api/v1/auth/link": { "post": { "operationId": "v1.auth.link", "description": "Always answers 202 with the same body whether or not the address\nbelongs to an operator user. An unauthenticated endpoint that answered\ndifferently would be an account-enumeration oracle, and this one is\nreachable by anyone on the internet.", "summary": "Request a sign-in link", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "If that address belongs to an operator account, a sign-in link is on its way." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/api/v1/auth/rotate": { "post": { "operationId": "v1.auth.rotate", "summary": "Rotate the presented token. The old one dies in the same request", "tags": [ "Auth" ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "token_id": { "type": "string" }, "device_name": { "type": "string" }, "abilities": { "type": "array", "items": {} }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "token", "token_id", "device_name", "abilities", "expires_at" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "rotation_not_available" }, "message": { "type": "string", "const": "This credential cannot be rotated." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/api/v1/bookings": { "get": { "operationId": "v1.bookings.index", "tags": [ "Bookings" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "cancelled", "all" ] } } ], "responses": { "200": { "description": "Paginated set of `BookingResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "bookings:read" ] } }, "/api/v1/bookings/{ref}": { "get": { "operationId": "v1.bookings.show", "tags": [ "Bookings" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`BookingDetailResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BookingDetailResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "bookings:read" ] } }, "/api/v1/bookings/{ref}/driver": { "post": { "operationId": "v1.bookings.driver", "description": "Unlike the portal form, this endpoint will not create a driver on the\nfly from a loose name: the roster has its own endpoint, and an\nintegrator retrying a failed call must not silently mint duplicate\ndriver records as a side effect of an assignment.", "summary": "Assign (or re-assign) a driver and vehicle registration", "tags": [ "Bookings" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "driver_id": { "type": "integer" }, "vehicle_reg": { "type": "string", "maxLength": 20 }, "vehicle_id": { "type": [ "integer", "null" ] } }, "required": [ "driver_id", "vehicle_reg" ] } } } }, "responses": { "200": { "description": "`BookingDetailResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BookingDetailResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "trip_cancelled", "booking_not_confirmed" ] }, "message": { "type": [ "string", "null" ], "enum": [ "This one isn't confirmed yet — the customer hasn't finished booking it, so there's no job to crew and no date you're committed to. Your price stands, and we'll tell you the moment it's confirmed so you can name your driver then.", "This trip was booked and then cancelled, so there's nothing here to confirm — you don't have this job, and nothing will be charged. A cancelled trip can't be re-booked, so nothing more will come of this one: you're free to release the date. If the customer still wants to travel they'll start a new trip, and we'll ask you to quote it then.", null ] } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "bookings:read", "drivers:write" ] } }, "/api/v1/drivers": { "get": { "operationId": "v1.drivers.index", "tags": [ "Drivers" ], "responses": { "200": { "description": "Paginated set of `DriverResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriverResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "drivers:read" ] }, "post": { "operationId": "v1.drivers.store", "description": "`operator_id` is stamped from the token, never taken from the body —\nan `operator_id` in the payload is ignored rather than honoured, which\nis why the attributes are assembled explicitly instead of merged from\nthe validated array wholesale.", "summary": "Add a driver to the roster", "tags": [ "Drivers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "phone": { "type": [ "string", "null" ], "maxLength": 24 }, "license_number": { "type": [ "string", "null" ], "maxLength": 80 }, "license_kind": { "type": [ "string", "null" ], "maxLength": 40 }, "license_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "dbs_check_kind": { "type": [ "string", "null" ], "enum": [ "enhanced", "enhanced_barred", "standard", "basic", null ] }, "dbs_certificate_number": { "type": [ "string", "null" ], "maxLength": 64 }, "dbs_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "invite_now": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "`DriverResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DriverResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "drivers:write" ] } }, "/api/v1/drivers/{id}/reinvite": { "post": { "operationId": "v1.drivers.reinvite", "description": "A driver id belonging to another operator answers 404, not 403: a 403\nwould confirm the id exists, which is all someone needs to walk the\ntable.", "summary": "Re-send the driver's app sign-in link", "tags": [ "Drivers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "invited": { "type": "boolean" } }, "required": [ "id", "invited" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "drivers:write" ] } }, "/api/v1/jobs": { "get": { "operationId": "v1.jobs.index", "tags": [ "Jobs" ], "parameters": [ { "name": "filter", "in": "query", "description": "Rejected rather than defaulted: an integrator who sends\n`filter=new` and silently receives every job would build on a\nlist that does not mean what they think it means.", "schema": { "type": "string", "enum": [ "all", "fresh", "quoted", "closing", "expired" ] } } ], "responses": { "200": { "description": "Paginated set of `JobResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/JobResource" }, { "type": "object", "required": [ "my_quote" ] } ] } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "jobs:read" ] } }, "/api/v1/jobs/{ref}": { "get": { "operationId": "v1.jobs.show", "description": "The operator scope is part of the lookup rather than a check after it,\nso another operator's ref and a ref that does not exist produce the\nsame 404 — a 403 would confirm the reference is real, which is enough\nto enumerate the marketplace one guess at a time.", "summary": "One job, addressed by its trip ref", "tags": [ "Jobs" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`JobDetailResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetailResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "jobs:read" ] } }, "/api/v1/jobs/{ref}/confirm-booking-request": { "post": { "operationId": "v1.quotes.confirm_booking_request", "description": "This is the one endpoint on the surface that moves money, and it is the\nreason `Idempotency-Key` is mandatory rather than advisory.", "summary": "Accept a customer's booking request: charges their saved card for the\ndeposit and confirms the booking", "tags": [ "Quotes" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A value you generate for this attempt (a UUID is ideal). Required: it is what makes a retry safe. Replaying the same key returns the original response, marked with an `Idempotency-Replayed: true` header; reusing it with a different body is refused with 409.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Booking request answered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteActionResource" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "quotes:write" ] } }, "/api/v1/jobs/{ref}/decline": { "post": { "operationId": "v1.quotes.decline", "description": "The portal also lets an operator refer a peer for a finder fee. That is\ndeliberately not offered here: a referral names a real company and a\nreal person's email, our team then contacts them, and putting that\nbehind a machine credential invites automated referral spam against a\nfee we pay out. The rules for it live in the service either way, so\noffering it later is a route change and not a second implementation.", "summary": "Turn the job down", "tags": [ "Quotes" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional here. Supplying one still makes a retry return the original response rather than repeating the action.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Job declined.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteActionResource" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "quotes:write" ] } }, "/api/v1/jobs/{ref}/quote": { "post": { "operationId": "v1.quotes.store", "description": "Same operation either way, exactly as in the portal: the operator's\nquote for a job is a single row, so a second submit updates the first\nrather than adding a second offer the customer would have to choose\nbetween.", "summary": "Submit a quote, or revise one already submitted", "tags": [ "Quotes" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A value you generate for this attempt (a UUID is ideal). Required: it is what makes a retry safe. Replaying the same key returns the original response, marked with an `Idempotency-Replayed: true` header; reusing it with a different body is refused with 409.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Quote submitted or revised.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteActionResource" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "quotes:write" ] } }, "/api/v1/jobs/{ref}/reject-booking-request": { "post": { "operationId": "v1.quotes.reject_booking_request", "summary": "Turn a booking request down, with a reason the customer is shown", "tags": [ "Quotes" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional here. Supplying one still makes a retry return the original response rather than repeating the action.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_code": { "type": "string", "enum": [ "unavailable", "route", "price", "passengers", "overnight", "other" ] }, "reason_note": { "type": [ "string", "null" ], "maxLength": 600 } }, "required": [ "reason_code" ] } } } }, "responses": { "200": { "description": "Booking request turned down.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteActionResource" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "quotes:write" ] } }, "/api/v1/jobs/{ref}/unconfirm": { "post": { "operationId": "v1.quotes.unconfirm", "summary": "Drop a confirmed quote to `likely` without touching the price. The\ncustomer can still request to book; it just stops being instantly\nbookable", "tags": [ "Quotes" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional here. Supplying one still makes a retry return the original response rather than repeating the action.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Availability dropped to likely.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteActionResource" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "quotes:write" ] } }, "/api/v1/jobs/{ref}/withdraw": { "post": { "operationId": "v1.quotes.withdraw", "summary": "Retract a quote the customer has not yet acted on", "tags": [ "Quotes" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional here. Supplying one still makes a retry return the original response rather than repeating the action.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Quote withdrawn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteActionResource" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "quotes:write" ] } }, "/api/v1/me": { "get": { "operationId": "v1.me", "tags": [ "Me" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "operator": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "name": { "type": "string", "description": "`trading_name` is the operator's own name for itself\nand the one the portal shows. There is no `name`\ncolumn on this model — reading one returns null." } }, "required": [ "id", "ref", "name" ] }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "operator_user", "driver", "unknown" ] }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "type", "id", "name" ] }, "token": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "abilities": { "type": "array", "items": {} }, "expires_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "abilities", "expires_at", "last_used_at" ] } }, "required": [ "operator", "actor", "token" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/api/v1/payouts": { "get": { "operationId": "v1.payouts.index", "tags": [ "Payouts" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "maxLength": 32 } } ], "responses": { "200": { "description": "Paginated set of `PayoutResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "payouts:read" ] } }, "/api/v1/webhooks": { "get": { "operationId": "v1.webhooks.index", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Array of `WebhookResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "webhooks:manage" ] }, "post": { "operationId": "v1.webhooks.store", "description": "The signing secret is generated here rather than accepted from the\ncaller. The business webhook form takes one from its user, which means\na shared HMAC key is only ever as good as the weakest thing an\nintegrator typed into a form; minting it means every operator webhook\nis signed with 256 bits from a CSPRNG. It is returned exactly once, in\nthis response, and is unreadable afterwards.", "summary": "Subscribe a URL", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120 }, "endpoint_url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.offered", "booking.confirmed" ] }, "minItems": 1 } }, "required": [ "label", "endpoint_url", "events" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "webhooks:manage" ] } }, "/api/v1/webhooks/{id}": { "delete": { "operationId": "v1.webhooks.destroy", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "webhooks:manage" ] } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "operationId": "v1.webhooks.deliveries", "summary": "The delivery log for one subscription — what we sent, when, and what\nstatus came back. This is the endpoint an integrator uses to answer\n\"did you send it?\" without asking us", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated set of `WebhookDeliveryResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ], "x-required-abilities": [ "webhooks:manage" ] } }, "/driver/api/auth/exchange": { "post": { "operationId": "driver.api.auth.exchange", "description": "The native app's sign-in. Same single-use code, same throttle bucket\nand the same identity claim as verifyOtp() — the only difference is\nwhat the driver walks away with, and that no session is opened at all:\nminting a cookie for a client that cannot use one would hand a WebView\nan ambient credential this surface would then have to defend.\n\nThe raw token is returned exactly once, here. It is stored sha256-\nhashed, like every other credential in this codebase, and cannot be\nread back from anywhere afterwards.", "summary": "Verify the code and hand back a BEARER instead of a session (WP8)", "tags": [ "DriverAuth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "maxLength": 24 }, "country_code": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "code": { "type": "string", "maxLength": 12 }, "device_name": { "type": [ "string", "null" ], "maxLength": 60 } }, "required": [ "phone", "code" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "token_id": { "type": "string" }, "device_name": { "type": "string" }, "abilities": { "type": "array", "items": {} }, "expires_at": { "type": [ "string", "null" ] }, "driver": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] } }, "required": [ "token", "token_id", "device_name", "abilities", "expires_at", "driver" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/driver/api/auth/rotate": { "post": { "operationId": "driver.api.auth.rotate", "description": "The app calls this rather than asking for another SMS code, so a\ndriver's phone is not re-verified every 90 days on a handset that has\nnever left their hand. A session-authenticated caller has nothing to\nrotate and is told so rather than being handed a bearer it did not ask\nfor — which would be a way to escalate a WebView cookie into a\nlong-lived credential.", "summary": "Rotate the presented bearer. The old one dies in the same request", "tags": [ "DriverAuth" ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "token_id": { "type": "string" }, "device_name": { "type": "string" }, "abilities": { "type": "array", "items": {} }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "token", "token_id", "device_name", "abilities", "expires_at" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "rotation_not_available" }, "message": { "type": "string", "const": "This credential cannot be rotated." } }, "required": [ "error", "message" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/auth/sign-out": { "post": { "operationId": "driver.api.auth.signout", "description": "There is no cookie to clear on a native client, so without this\n\"sign out\" would leave a live 90-day credential on a phone the driver\nhas just handed back, sold, or lost. Takes effect on the very next\ncall: the token row is gone, not flagged.", "summary": "Sign this handset out — revoke the presented bearer", "tags": [ "DriverAuth" ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "no_token_to_revoke" }, "message": { "type": "string", "const": "This request was not made with an app token." } }, "required": [ "error", "message" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/bookings/{ref}/board": { "post": { "operationId": "driver.api.board", "description": "The scan token can be one of:\n - a per-entry pass_token (events shuttle, one_time mode)\n - a persistent profile qr_token (schools, daily mode) — the\n same QR scans every day, we find-or-create today's entry.\n\nPassengerManifestService::resolveScan() unifies the two and\nthe entry's canScanNow() decides whether this scan is allowed\nright now (rearm-per-day for schools, refuse-after-board for\nevents, valid-window for multi-day festival passes).", "summary": "QR boarding manifest. Driver scans a passenger QR; we record\nthe boarding event so the buyer-side manifest updates live", "tags": [ "DriverApp" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pass_token": { "type": "string", "maxLength": 64 }, "captured_at": { "type": "string", "format": "date-time" } }, "required": [ "pass_token", "captured_at" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" }, "passenger": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "ref": { "type": [ "string", "null" ] }, "seat": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "boarded_at": { "type": "string" }, "safety": { "type": "object", "properties": { "headline": { "type": "string" }, "note": { "type": "string" }, "truncated": { "type": "string" }, "emergency_contact": { "type": "string" }, "notice": { "type": "string", "description": "What this is and what it is not for, said to the driver on\nthe screen that shows it. Held server-side so the app cannot\nhold a copy that promises something we do not do." } }, "required": [ "headline", "note", "truncated", "emergency_contact", "notice" ] } }, "required": [ "id", "name", "ref", "seat", "mode", "boarded_at", "safety" ] } }, "required": [ "ok", "passenger" ] }, { "type": "object", "properties": { "already_boarded": { "type": "boolean" }, "mode": { "type": "string" }, "boarded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "already_boarded", "mode", "boarded_at" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/bookings/{ref}/driving/start": { "post": { "operationId": "driver.api.driving_start", "summary": "\"Start driving\" — the only thing that ever opens the tracking window", "tags": [ "DriverApp" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "driving_session": { "type": "object", "properties": { "id": { "type": "integer" }, "booking_id": { "type": "integer" }, "started_at": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "booking_id", "started_at", "expires_at" ] } }, "required": [ "ok", "driving_session" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "428": { "description": "428 Precondition Required: the app must do something first,\nand it is not an authorisation failure. Distinguishable from\n\"no session\" on purpose — they need different UI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "gps_consent_required" }, "required_version": { "type": "string" } }, "required": [ "error", "required_version" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/bookings/{ref}/driving/stop": { "post": { "operationId": "driver.api.driving_stop", "summary": "Stop driving. Location stops being accepted the moment this lands", "tags": [ "DriverApp" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "closed": { "type": "integer", "minimum": 0 } }, "required": [ "ok", "closed" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/bookings/{ref}/dvir": { "post": { "operationId": "driver.api.dvir", "description": "WP7 rewired the far end of this. It used to drop the whole report into\n`bookings.meta['dvir']` — one mutable slot, so the second check erased\nthe first — and its promise to \"flag any fail items into the operator's\n * inbox\" was never implemented; nothing anywhere read the blob back. It\nnow writes a `vehicle_inspection_reports` row that cannot be edited or\ndeleted afterwards, and the operator is told.\n\nThe endpoint no longer treats every fail alike. `DvirChecklist` decides\nserver-side which failures stop the vehicle; the client may escalate an\nitem with `prohibits_use` but can never clear one. See\n`VehicleInspectionRecorder` for who is told and what the hold does.", "summary": "Digital Vehicle Inspection Report — the driver's walkaround check", "tags": [ "DriverApp" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "pre_trip", "post_trip", null ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 60 }, "label": { "type": "string", "maxLength": 160 }, "status": { "type": "string", "enum": [ "pass", "fail", "n_a" ] }, "notes": { "type": [ "string", "null" ], "maxLength": 500 }, "prohibits_use": { "type": [ "boolean", "null" ], "description": "The driver's own judgement, and it only ever adds: the server's\ncatalogue is what decides the rest." } }, "required": [ "key", "label", "status" ] }, "minItems": 1 }, "inspected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the walkaround was done, which is not when it uploaded —\nan offline check must not claim the time it synced." }, "odometer_reading": { "type": [ "integer", "null" ], "description": "The reading off the dash, in whatever unit that dash reads.\nThe app is told which by `me().driver.distance_unit` and\nlabels the field with it; the server re-resolves it from the\noperator's country when it records, so the unit on the record\nnever depends on what the client believed.", "minimum": 0 }, "fuel_pct": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "photo_paths": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "outcome": { "type": "string" }, "fails": { "type": "integer" }, "prohibits_use": { "type": "boolean" }, "message": { "type": "string", "description": "The one thing the driver cannot work out for themselves.", "enum": [ "Do not move this vehicle. Your operator has been told and has to sign it off.", "Logged. Your operator can see what you found.", "Check recorded. You are good to go." ] } }, "required": [ "ok", "ref", "outcome", "fails", "prohibits_use", "message" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/bookings/{ref}/lifecycle": { "post": { "operationId": "driver.api.lifecycle", "description": "Validation is forgiving (any-state-to-any-state) so the app\nstays usable when reality doesn't follow the textbook order.\nThe full state-machine guard is Phase 4 territory.\n\n`arrived` is the trip's completion, and completion is where the\nowner's decision says tracking stops — so it closes the driving\nsession here rather than relying on the app to remember.", "summary": "Booking lifecycle controls. The driver app advances state as\nthe trip unfolds — en_route → on_site → boarding → departed\n→ arrived. Each transition is audited and broadcasts to the\nbuyer-side ops dashboard", "tags": [ "DriverApp" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lifecycle": { "type": "string", "enum": [ "en_route", "on_site", "boarding", "departed", "arrived" ] } }, "required": [ "lifecycle" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "lifecycle": { "type": "string" } }, "required": [ "ok", "lifecycle" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "vehicle_defect_hold" }, "message": { "type": "string", "const": "This vehicle is on hold after your check. Your operator has to sign it off before it goes anywhere." }, "items": { "type": "array", "items": {} } }, "required": [ "error", "message", "items" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/bookings/{ref}/manifest": { "get": { "operationId": "driver.api.manifest", "description": "── WHY A LIST AND NOT ONLY A SCAN RESULT ─────────────────────────────\n\nThe scan tells a driver about a child who is already climbing the step.\nThat is the wrong moment to learn that one of the forty must not travel\nalone, or which one carries an EpiPen — by then the decision has been\nmade. A driver who reads the list before the doors open can act on it;\none who only ever sees a note post-hoc is being informed, not equipped.\nThe scan payload carries it as well, because a driver who did not read\nthe list must not therefore miss it.\n\n── WHAT BOUNDS IT ────────────────────────────────────────────────────\n\n`resolveAssignment()` — the same guard every other endpoint on this\ncontroller uses — resolves `{ref}` to a booking held by one of this\nprincipal's ACTIVE roster rows, and answers a booking that belongs to\nsomebody else identically to one that does not exist. A driver\ntherefore sees the passengers on the job they are actually driving and\non no other, and a roster row archived this morning takes its bookings\nout of this response this afternoon. Nothing here is global, and nothing\nhere takes an id from the request body.\n\n── WHY THE FULL NOTE TRAVELS ─────────────────────────────────────────\n\n`headline` is what the row shows; `note` is the whole of what the school\nwrote and it is in the payload too, so opening a passenger is a tap\nrather than a round trip. A driver at a kerbside with one bar of signal\nmust not have to fetch the second half of a sentence about anaphylaxis.\nThe response is `no-store` for the same reason the console reveal is.\n\n── AUDITED, ONCE, BEFORE IT RENDERS ──────────────────────────────────\n\nOne `manifest.safety_notes_to_driver` row naming the profiles disclosed\nand the driver who was handed them — written before the payload is\nbuilt, so a failure between here and the wire still leaves the record.", "summary": "The passengers on this job, with what the school said about them", "tags": [ "DriverApp" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "booking_ref": { "type": "string" }, "total": { "type": "integer", "minimum": 0 }, "boarded": { "type": "integer", "minimum": 0 }, "flagged": { "type": "integer", "description": "How many rows carry something the driver has to act on. Shown as\na count above the list so a coach with one EpiPen among forty\nannounces itself rather than waiting to be scrolled to." }, "passengers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "ref": { "type": [ "string", "null" ] }, "seat": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "boarded_at": { "type": "string" }, "safety": { "type": "object", "properties": { "headline": { "type": "string" }, "note": { "type": "string" }, "truncated": { "type": "string" }, "emergency_contact": { "type": "string" }, "notice": { "type": "string", "description": "What this is and what it is not for, said to the driver on\nthe screen that shows it. Held server-side so the app cannot\nhold a copy that promises something we do not do." } }, "required": [ "headline", "note", "truncated", "emergency_contact", "notice" ] } }, "required": [ "id", "name", "ref", "seat", "mode", "boarded_at", "safety" ] } } }, "required": [ "booking_ref", "total", "boarded", "flagged", "passengers" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/devices": { "post": { "operationId": "driver.api.devices", "tags": [ "DriverApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_uuid": { "type": "string", "maxLength": 64 }, "platform": { "type": "string", "enum": [ "ios", "android", "web" ] }, "app_version": { "type": [ "string", "null" ], "maxLength": 24 }, "os_version": { "type": [ "string", "null" ], "maxLength": 32 }, "push_token": { "type": [ "string", "null" ], "maxLength": 400 }, "push_provider": { "type": [ "string", "null" ], "enum": [ "fcm", "apns", "web_push", null ] } }, "required": [ "device_uuid", "platform" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "integer" }, "ok": { "type": "boolean" } }, "required": [ "device_id", "ok" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "description": "An error\n\nAn error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "no_active_roster_link" ] } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "device_registered_to_another_driver" ] } }, "required": [ "message" ] } ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/gps-consent": { "post": { "operationId": "driver.api.gps_consent", "description": "Recorded per roster row, because the operator is who the location is\nshared with, and each has to be revocable on its own. One call\nrecords it for every operator the driver currently drives for, and\nDriverIdentityService carries it to any operator added later, so the\ndriver is asked once per wording rather than once per employer.", "summary": "Record the driver's consent to job-bounded location collection", "tags": [ "DriverApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_version": { "type": "string", "maxLength": 32 }, "country_code": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "accepted": { "type": "boolean" } }, "required": [ "policy_version" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "gps": { "type": "object", "properties": { "consent_version": { "type": "string" }, "consent_required": { "type": "boolean" }, "retention_days": { "type": "integer" }, "ping_batch_max": { "type": "integer", "description": "The client chunks its offline queue to this. Served rather\nthan hardcoded in the app so the two cannot drift: a client\nthat batches larger than the server accepts cannot flush at\nall, and the queue wedges. Same constant the validator uses." }, "stale_after_minutes": { "type": "integer", "description": "Minutes of silence after which the operator is told the trace\nhas gone dark (DetectStaleDriverLocation). The app shows the\ndriver the same number so the warning they see and the alert\ntheir operator gets are the same event." }, "statement": { "type": "string", "description": "The exact wording the owner fixed on 2026-08-04. It is the same\ntext in the consent screen, the operator DPA and both store\ndeclarations, so it is served from one place — App\\Support\\\nGpsConsentCopy — and the app hardcodes none of it. A client\nholding its own copy is a client that can promise something the\nserver does not do." }, "statements": { "type": "array", "prefixItems": [ { "type": "string", "const": "Your location is recorded only while you are driving a job you have accepted." }, { "type": "string", "const": "It starts when you tap “Start driving” and stops when the job is complete." }, { "type": "string", "const": "It is shared with your operator and with the client for that job, and with no one else." }, { "type": "string", "const": "Your location is never recorded off shift." }, { "type": "string" } ], "minItems": 5, "maxItems": 5, "additionalItems": false }, "enforcement": { "type": "string" }, "withdrawal": { "type": "string" }, "inspection_records": { "type": "string" }, "operators": { "type": "array", "items": { "type": "string" } } }, "required": [ "consent_version", "consent_required", "retention_days", "ping_batch_max", "stale_after_minutes", "statement", "statements", "enforcement", "withdrawal", "inspection_records", "operators" ] } }, "required": [ "ok", "gps" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/me": { "get": { "operationId": "driver.api.me", "tags": [ "DriverApp" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "driver": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "identity_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "operator_id": { "type": [ "integer", "null" ] }, "operator_ids": { "type": "array", "items": {} }, "roster_ids": { "type": "object", "additionalProperties": { "type": "integer" } }, "app_installed_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "distance_unit": { "type": "string", "description": "Which unit this driver's vehicles read in. Shipped rather than assumed in TypeScript, for the same\nreason the checklist below is: the app must ask for the\nodometer in the unit the server will record it in. The\nDVIR field was hardcoded \"Odometer (km)\" in every market,\nso a British driver typed a mile reading into a field\nlabelled km and the platform wrote it to a legal record\n60% short.\n\nFrom the OPERATOR's country, not the trip's: the odometer\nbelongs to the vehicle, and a British coach on a French\njob still has a mile dash." } }, "required": [ "id", "identity_id", "name", "operator_id", "operator_ids", "roster_ids", "app_installed_at", "last_seen_at", "distance_unit" ] }, "gps": { "type": "object", "properties": { "consent_version": { "type": "string" }, "consent_required": { "type": "boolean" }, "retention_days": { "type": "integer" }, "ping_batch_max": { "type": "integer", "description": "The client chunks its offline queue to this. Served rather\nthan hardcoded in the app so the two cannot drift: a client\nthat batches larger than the server accepts cannot flush at\nall, and the queue wedges. Same constant the validator uses." }, "stale_after_minutes": { "type": "integer", "description": "Minutes of silence after which the operator is told the trace\nhas gone dark (DetectStaleDriverLocation). The app shows the\ndriver the same number so the warning they see and the alert\ntheir operator gets are the same event." }, "statement": { "type": "string", "description": "The exact wording the owner fixed on 2026-08-04. It is the same\ntext in the consent screen, the operator DPA and both store\ndeclarations, so it is served from one place — App\\Support\\\nGpsConsentCopy — and the app hardcodes none of it. A client\nholding its own copy is a client that can promise something the\nserver does not do." }, "statements": { "type": "array", "prefixItems": [ { "type": "string", "const": "Your location is recorded only while you are driving a job you have accepted." }, { "type": "string", "const": "It starts when you tap “Start driving” and stops when the job is complete." }, { "type": "string", "const": "It is shared with your operator and with the client for that job, and with no one else." }, { "type": "string", "const": "Your location is never recorded off shift." }, { "type": "string" } ], "minItems": 5, "maxItems": 5, "additionalItems": false }, "enforcement": { "type": "string" }, "withdrawal": { "type": "string" }, "inspection_records": { "type": "string" }, "operators": { "type": "array", "items": { "type": "string" } } }, "required": [ "consent_version", "consent_required", "retention_days", "ping_batch_max", "stale_after_minutes", "statement", "statements", "enforcement", "withdrawal", "inspection_records", "operators" ] }, "dvir_checklist": { "type": "array", "description": "The walkaround catalogue the DVIR endpoint scores against. Shipped rather than duplicated in TypeScript so the list the\ndriver ticks IS the list the server scores. A hardcoded client\ncopy drifts the moment an item is added here, and the drift is\ninvisible: the app would render a check the server does not\nknow (reported, but never grounding) or omit one it does.", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "section": { "type": "string" }, "prohibits_use": { "type": "string" } }, "required": [ "key", "label", "section", "prohibits_use" ] } }, "driving_sessions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "description": "A row selected by the endpoint's own query. The exact set of fields is chosen at query time and is not derivable from the code, so it is left undescribed here rather than described wrongly." } } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "ref": { "type": "string" }, "status": { "type": "string" }, "operator": { "type": "string" }, "lifecycle": { "type": [ "string", "null" ], "description": "The owner's four-state vocabulary, resolved server-side from\nthe stored dispatcher stage — see LIFECYCLE_LABELS." }, "lifecycle_at": { "type": [ "string", "null" ] }, "vehicle_reg": { "type": [ "string", "null" ] }, "passengers": { "type": [ "integer", "null" ] }, "trip": { "type": [ "object", "null" ], "properties": { "ref": { "type": "string" }, "country_code": { "type": "string", "description": "The zone abbreviation the app prints (\"BST\", \"AEST\") is\nambiguous without it — the shared formatTripDateTime()\nhelper takes a country for exactly that reason." }, "pickup_at": { "type": "string" }, "pickup_timezone": { "type": [ "string", "null" ] }, "return_at": { "type": "string" }, "return_timezone": { "type": [ "string", "null" ] }, "pickup": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "line1": { "type": [ "string", "null" ] }, "locality": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } }, "required": [ "label", "line1", "locality", "postal_code", "lat", "lng" ] }, "dropoff": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "line1": { "type": [ "string", "null" ] }, "locality": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } }, "required": [ "label", "line1", "locality", "postal_code", "lat", "lng" ] }, "vehicle_type": { "type": [ "string", "null" ] }, "accessibility": { "type": [ "array", "null" ], "items": {} } }, "required": [ "ref", "country_code", "pickup_at", "pickup_timezone", "return_at", "return_timezone", "pickup", "dropoff", "vehicle_type", "accessibility" ] }, "driving_session": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "started_at": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "started_at", "expires_at" ] }, "vehicle_defect_hold": { "type": [ "object", "null" ], "properties": { "items": { "type": "array", "items": {} }, "held_at": { "type": [ "string", "null" ] } }, "required": [ "items", "held_at" ] }, "manifest": { "type": "object", "properties": { "total": { "type": "integer" }, "boarded": { "type": "integer" } }, "required": [ "total", "boarded" ] } }, "required": [ "id", "ref", "status", "operator", "lifecycle", "lifecycle_at", "vehicle_reg", "passengers", "trip", "driving_session", "vehicle_defect_hold", "manifest" ] } } }, "required": [ "driver", "gps", "dvir_checklist", "driving_sessions", "assignments" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/ping": { "post": { "operationId": "driver.api.ping", "tags": [ "DriverApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "booking_id": { "type": "integer", "description": "No longer nullable. An off-job ping is not a thing that can be\nsent, which is the schema-level half of the owner's decision." }, "device_id": { "type": [ "integer", "null" ] }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_m": { "type": [ "number", "null" ] }, "heading_deg": { "type": [ "number", "null" ] }, "speed_mps": { "type": [ "number", "null" ] }, "battery_pct": { "type": [ "number", "null" ] }, "captured_at": { "type": "string", "format": "date-time" } }, "required": [ "booking_id", "lat", "lng", "captured_at" ] } } } }, "responses": { "200": { "description": "`DrivingSession`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, { "type": "object", "description": "A row selected by the endpoint's own query. The exact set of fields is chosen at query time and is not derivable from the code, so it is left undescribed here rather than described wrongly." }, { "type": "null" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "428": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "gps_consent_required" }, "required_version": { "type": "string" } }, "required": [ "error", "required_version" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/ping/batch": { "post": { "operationId": "driver.api.ping_batch", "description": "THE SIZE CHECK IS BEFORE VALIDATION AND ANSWERS IN A CODE THE CLIENT\nCAN ACT ON. It used to be `max:200` inside the validator, which came\nback as a generic 422 with a human sentence in it. The client\n(capacitor.ts PingQueue) only clears its queue on a 2xx, so once a\ndriver had banked more than 200 samples — one bad stretch of signal is\nenough — every flush for the rest of that job, and every job after it,\nposted the same oversized body and got the same refusal. localStorage\noutlives the app, so the queue never came back: the driver was offline\npermanently and live tracking stopped with no signal to anyone.\n\n413 + `{error: 'batch_too_large', max: N}` is an instruction: split at\n`max` and retry. `max` is the same config value the client is told up\nfront in `gps.ping_batch_max`, so a well-behaved client never sees this\nat all — it is the recovery path for one that has drifted.", "summary": "Flush of the client's offline ping queue", "tags": [ "DriverApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pings": { "type": "array", "items": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "device_id": { "type": [ "integer", "null" ] }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_m": { "type": [ "number", "null" ] }, "heading_deg": { "type": [ "number", "null" ] }, "speed_mps": { "type": [ "number", "null" ] }, "battery_pct": { "type": [ "number", "null" ] }, "captured_at": { "type": "string", "format": "date-time" } }, "required": [ "booking_id", "lat", "lng", "captured_at" ] }, "minItems": 1, "maxItems": 0 } }, "required": [ "pings" ] } } } }, "responses": { "200": { "description": "`DrivingSession`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" }, "inserted": { "type": "integer" } }, "required": [ "ok", "inserted" ] }, { "type": "object", "description": "A row selected by the endpoint's own query. The exact set of fields is chosen at query time and is not derivable from the code, so it is left undescribed here rather than described wrongly." }, { "type": "null" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "413": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "batch_too_large" }, "max": { "type": "integer" }, "sent": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "error", "max", "sent", "message" ] } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "428": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "gps_consent_required" }, "required_version": { "type": "string" } }, "required": [ "error", "required_version" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/privacy": { "get": { "operationId": "driver.api.privacy", "tags": [ "DriverPrivacy" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "properties": { "identity_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "operators": { "type": "array", "items": { "type": "string" } } }, "required": [ "identity_id", "name", "phone", "email", "operators" ] }, "holds": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "what": { "type": "string", "const": "Recorded positions" }, "count": { "type": "integer", "minimum": 0 }, "kept_for": { "type": "string" }, "why": { "type": "string", "const": "So your operator and the job's client can see the coach on the day." }, "erasable": { "type": "boolean" } }, "required": [ "what", "count", "kept_for", "why", "erasable" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Driving windows" }, "count": { "type": "integer", "minimum": 0 }, "kept_for": { "type": "string" }, "why": { "type": "string", "const": "When you started and finished driving each job. No location in them." }, "erasable": { "type": "boolean" } }, "required": [ "what", "count", "kept_for", "why", "erasable" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Vehicle checks" }, "count": { "type": "integer", "minimum": 0 }, "kept_for": { "type": "string" }, "why": { "type": "string", "const": "Your operator's roadworthiness record. They cannot be changed or deleted." }, "erasable": { "type": "boolean" } }, "required": [ "what", "count", "kept_for", "why", "erasable" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Registered handsets" }, "count": { "type": "integer", "minimum": 0 }, "kept_for": { "type": "string", "const": "until you sign out on the handset or your operator archives you" }, "why": { "type": "string", "const": "So job alerts reach the right phone." }, "erasable": { "type": "boolean" } }, "required": [ "what", "count", "kept_for", "why", "erasable" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Location consent records" }, "count": { "type": "integer", "minimum": 0 }, "kept_for": { "type": "string", "const": "indefinitely" }, "why": { "type": "string" }, "erasable": { "type": "boolean" } }, "required": [ "what", "count", "kept_for", "why", "erasable" ] } ], "minItems": 5, "maxItems": 5, "additionalItems": false }, "statement": { "type": "string" }, "withdrawal": { "type": "string" }, "inspection_records": { "type": "string" } }, "required": [ "subject", "holds", "statement", "withdrawal", "inspection_records" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/privacy/erase": { "post": { "operationId": "driver.api.privacy.erase", "summary": "Erase what can be erased. The response is a receipt, not an \"ok\"", "tags": [ "DriverPrivacy" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "erased": { "type": "object", "properties": { "positions": { "type": "integer" }, "devices_revoked": { "type": "integer" }, "consents_withdrawn": { "type": "integer" }, "driving_windows_closed": { "type": "integer" } }, "required": [ "positions", "devices_revoked", "consents_withdrawn", "driving_windows_closed" ] }, "kept": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "what": { "type": "string", "const": "Vehicle checks" }, "count": { "type": "integer", "minimum": 0 }, "why": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "inspected_at": { "type": "string" }, "outcome": { "type": "string" }, "may_be_deleted_after": { "type": "string" } }, "required": [ "ref", "inspected_at", "outcome", "may_be_deleted_after" ] } } }, "required": [ "what", "count", "why", "items" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Driving windows" }, "count": { "type": "integer", "minimum": 0 }, "why": { "type": "string" } }, "required": [ "what", "count", "why" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Consent records" }, "count": { "type": "integer", "minimum": 0 }, "why": { "type": "string" } }, "required": [ "what", "count", "why" ] }, { "type": "object", "properties": { "what": { "type": "string", "const": "Your operator's roster entry" }, "count": { "type": "integer", "minimum": 0 }, "why": { "type": "string" } }, "required": [ "what", "count", "why" ] } ], "minItems": 4, "maxItems": 4, "additionalItems": false } }, "required": [ "ok", "erased", "kept" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } }, "/driver/api/privacy/export": { "get": { "operationId": "driver.api.privacy.export", "description": "Two reasons, and the second is the one that matters on this endpoint.\n\n1. A raw model row publishes an undescribed object in the OpenAPI\n document (`OpenApiSpecUpToDateTest::test_no_new_endpoint_hides_its_shape_behind_a_model`),\n so the reference cannot state what a subject-access export contains —\n which is the exact question its reader is asking. The generator is\n caught out by `->get([...])` because the column list is chosen at\n query time and the analyser only sees the model.\n2. `driver_devices` carries a **push token**, which is a credential, and\n `driver_identities` carries `remember_token`. Selecting columns is a\n promise a future edit can break in one word; naming each field here\n means a leak has to be typed out deliberately. Neither token appears\n below, and `DriverPrivacyRequestTest::test_the_export_contains_no_credential_of_any_kind`\n asserts the rendered payload contains no credential of any kind.", "summary": "EVERY ROW IS BUILT AS A LITERAL, NOT HANDED BACK AS AN ELOQUENT MODEL", "tags": [ "DriverPrivacy" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "exported_at": { "type": "string" }, "subject": { "type": "object", "properties": { "identity_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "operators": { "type": "array", "items": { "type": "string" } } }, "required": [ "identity_id", "name", "phone", "email", "operators" ] }, "roster_entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "operator": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "app_installed_at": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "operator", "name", "email", "phone", "app_installed_at", "created_at" ] } }, "devices": { "type": "array", "description": "The handsets registered to you. The push credential each one\nholds is deliberately not included: it is an address for\nmessaging the phone rather than information about you, and an\nexport that handed one out would have published a way to reach\nthat handset. Which transport was in use is included instead. (This comment becomes the field's description in the published\nAPI reference, so it is written for that reader. The reason it\nis enforced field by field rather than by a column list is in\nthe method docblock above.)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "operator_driver_id": { "type": "integer" }, "device_uuid": { "type": "string" }, "platform": { "type": "string" }, "app_version": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "push_provider": { "type": [ "string", "null" ] }, "registered_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "revoked_at": { "type": "string" } }, "required": [ "id", "operator_driver_id", "device_uuid", "platform", "app_version", "os_version", "push_provider", "registered_at", "last_seen_at", "revoked_at" ] } }, "location_consents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "operator_driver_id": { "type": "integer" }, "policy_version": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "consented_at": { "type": "string" }, "revoked_at": { "type": "string" }, "ip": { "type": [ "string", "null" ] } }, "required": [ "id", "operator_driver_id", "policy_version", "country_code", "consented_at", "revoked_at", "ip" ] } }, "driving_windows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "booking_id": { "type": "integer" }, "operator_driver_id": { "type": "integer" }, "started_at": { "type": "string" }, "expires_at": { "type": "string" }, "ended_at": { "type": "string" }, "end_reason": { "type": [ "string", "null" ] } }, "required": [ "id", "booking_id", "operator_driver_id", "started_at", "expires_at", "ended_at", "end_reason" ] } }, "positions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "booking_id": { "type": "integer" }, "driving_session_id": { "type": [ "integer", "null" ], "description": "The driving window this position belongs to — a row id\nin `driving_windows` above, not a credential. It is what\nlets a reader see which job each point came from." }, "lat": { "type": "number" }, "lng": { "type": "number" }, "accuracy_m": { "type": [ "number", "null" ] }, "heading_deg": { "type": [ "number", "null" ] }, "speed_mps": { "type": [ "number", "null" ] }, "battery_pct": { "type": [ "number", "null" ] }, "captured_at": { "type": "string" }, "received_at": { "type": "string" } }, "required": [ "id", "booking_id", "driving_session_id", "lat", "lng", "accuracy_m", "heading_deg", "speed_mps", "battery_pct", "captured_at", "received_at" ] } }, "positions_total": { "type": "integer", "minimum": 0 }, "positions_truncated": { "type": "boolean" }, "positions_note": { "type": [ "string", "null" ] }, "vehicle_checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "ref": { "type": "string" }, "booking_id": { "type": "integer" }, "operator_driver_id": { "type": "integer" }, "vehicle_reg": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "items": { "type": "array", "description": "Each checklist line, named field by field for the same\nreason as everything else here — handing back the stored\nJSON blob leaves the document describing it as a string.", "items": {} }, "odometer_reading": { "type": [ "integer", "null" ], "description": "Exported as the pair, because the reading on its own is\nnot a fact the driver can check. `null` unit = a reading\ntaken before the unit was recorded; see the migration." }, "odometer_unit": { "type": [ "string", "null" ] }, "fuel_pct": { "type": [ "integer", "null" ] }, "outcome": { "type": "string" }, "fail_count": { "type": "integer" }, "prohibiting_count": { "type": "integer" }, "inspected_at": { "type": "string" }, "retain_until": { "type": "string" } }, "required": [ "id", "ref", "booking_id", "operator_driver_id", "vehicle_reg", "kind", "items", "odometer_reading", "odometer_unit", "fuel_pct", "outcome", "fail_count", "prohibiting_count", "inspected_at", "retain_until" ] } }, "retention": { "type": "object", "properties": { "positions_days": { "type": "integer" }, "driving_windows_days": { "type": "integer" }, "vehicle_checks_months": { "type": "integer" } }, "required": [ "positions_days", "driving_windows_days", "vehicle_checks_months" ] } }, "required": [ "exported_at", "subject", "roster_entries", "devices", "location_consents", "driving_windows", "positions", "positions_total", "positions_truncated", "positions_note", "vehicle_checks", "retention" ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": {} } ] } } }, "components": { "schemas": { "ApiError": { "type": "object", "description": "Every failure on this API has the same shape. Branch on `error.code`, which is stable; `error.message` is written for a human and may change.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, machine-readable reason.", "examples": [ "missing_ability" ] }, "message": { "type": "string", "description": "Plain-language explanation, safe to show to the person operating your system." }, "missing_ability": { "type": "string", "description": "On a 403 from the ability check: the one scope this key is short of." }, "fields": { "type": "object", "description": "On a 422 from validation: the offending fields, each with one or more messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "BookingDetailResource": { "type": "object", "properties": { "ref": { "type": "string" }, "trip_ref": { "type": "string" }, "status": { "type": "string" }, "status_changed_at": { "type": [ "string", "null" ] }, "currency_code": { "type": "string" }, "total_minor": { "type": "integer" }, "deposit_minor": { "type": "integer" }, "balance_minor": { "type": "integer" }, "platform_fee_minor": { "type": "integer" }, "operator_payout_minor": { "type": "integer" }, "balance_due_at": { "type": [ "string", "null" ] }, "payment_mode": { "type": "string" }, "pickup_at": { "type": [ "string", "null" ] }, "return_at": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "group_size": { "type": [ "integer", "null" ] }, "pickup": { "anyOf": [ { "description": "Won job, so the exact addresses are available — see\nPlaceDetailResource.", "$ref": "#/components/schemas/PlaceDetailResource" }, { "type": "null" } ] }, "dropoff": { "anyOf": [ { "$ref": "#/components/schemas/PlaceDetailResource" }, { "type": "null" } ] }, "driver_id": { "type": [ "integer", "null" ] }, "vehicle_reg": { "type": [ "string", "null" ], "description": "The operator's own vehicle registration. Booking::vehicleRegMasked()\nexists to hide it from the CUSTOMER until close to travel; the\noperator is the party that entered it." }, "cancelled_at": { "type": [ "string", "null" ] }, "cancelled_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "use_mode": { "type": "string" }, "trip_type": { "type": "string" }, "duration_minutes": { "type": [ "integer", "null" ] }, "vehicle_class": { "type": "string" }, "vehicle_type_hint": { "type": [ "string", "null" ] }, "occasion": { "type": [ "string", "null" ] }, "accessibility": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." }, "extras": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." }, "luggage": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." }, "requirements_summary": { "type": [ "string", "null" ] }, "stops": { "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer" }, "role": { "type": "string" }, "place": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "locality": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ] } }, "required": [ "label", "line1", "line2", "locality", "region", "postal_code", "country_code", "lat", "lng", "timezone" ] }, "duration_minutes": { "type": [ "integer", "null" ] } }, "required": [ "sequence", "role", "place", "duration_minutes" ] } }, "driver": { "anyOf": [ { "description": "The operator's own roster record, so a dispatch system can\nreconcile the assignment against its own driver list.", "$ref": "#/components/schemas/DriverResource" }, { "type": "null" } ] }, "quote": { "anyOf": [ { "description": "The quote this booking was won on, money verbatim.", "$ref": "#/components/schemas/QuoteMoneyResource" }, { "type": "null" } ] } }, "required": [ "ref", "trip_ref", "status", "status_changed_at", "currency_code", "total_minor", "deposit_minor", "balance_minor", "platform_fee_minor", "operator_payout_minor", "balance_due_at", "payment_mode", "pickup_at", "return_at", "timezone", "group_size", "pickup", "dropoff", "driver_id", "vehicle_reg", "cancelled_at", "cancelled_reason", "created_at", "use_mode", "trip_type", "duration_minutes", "vehicle_class", "vehicle_type_hint", "occasion", "accessibility", "extras", "luggage", "requirements_summary", "stops", "driver", "quote" ], "title": "BookingDetailResource" }, "BookingResource": { "type": "object", "properties": { "ref": { "type": "string" }, "trip_ref": { "type": "string" }, "status": { "type": "string" }, "status_changed_at": { "type": [ "string", "null" ] }, "currency_code": { "type": "string" }, "total_minor": { "type": "integer" }, "deposit_minor": { "type": "integer" }, "balance_minor": { "type": "integer" }, "platform_fee_minor": { "type": "integer" }, "operator_payout_minor": { "type": "integer" }, "balance_due_at": { "type": [ "string", "null" ] }, "payment_mode": { "type": "string" }, "pickup_at": { "type": [ "string", "null" ] }, "return_at": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "group_size": { "type": [ "integer", "null" ] }, "pickup": { "anyOf": [ { "description": "Won job, so the exact addresses are available — see\nPlaceDetailResource.", "$ref": "#/components/schemas/PlaceDetailResource" }, { "type": "null" } ] }, "dropoff": { "anyOf": [ { "$ref": "#/components/schemas/PlaceDetailResource" }, { "type": "null" } ] }, "driver_id": { "type": [ "integer", "null" ] }, "vehicle_reg": { "type": [ "string", "null" ], "description": "The operator's own vehicle registration. Booking::vehicleRegMasked()\nexists to hide it from the CUSTOMER until close to travel; the\noperator is the party that entered it." }, "cancelled_at": { "type": [ "string", "null" ] }, "cancelled_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "ref", "trip_ref", "status", "status_changed_at", "currency_code", "total_minor", "deposit_minor", "balance_minor", "platform_fee_minor", "operator_payout_minor", "balance_due_at", "payment_mode", "pickup_at", "return_at", "timezone", "group_size", "pickup", "dropoff", "driver_id", "vehicle_reg", "cancelled_at", "cancelled_reason", "created_at" ], "title": "BookingResource" }, "DriverResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "license_number": { "type": [ "string", "null" ] }, "license_kind": { "type": [ "string", "null" ] }, "license_expires_at": { "type": [ "string", "null" ] }, "dbs_status": { "type": [ "string", "null" ] }, "dbs_check_kind": { "type": [ "string", "null" ] }, "dbs_certificate_number": { "type": [ "string", "null" ] }, "dbs_expires_at": { "type": [ "string", "null" ] }, "app_ready": { "type": "boolean", "description": "Whether this driver can be assigned to a booking that requires\nthe driver app. Read through the model's own rule." }, "app_installed_at": { "type": [ "string", "null" ] }, "app_last_active_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone", "status", "license_number", "license_kind", "license_expires_at", "dbs_status", "dbs_check_kind", "dbs_certificate_number", "dbs_expires_at", "app_ready", "app_installed_at", "app_last_active_at", "created_at" ], "title": "DriverResource" }, "JobDetailResource": { "type": "object", "properties": { "ref": { "type": "string", "description": "The job is addressed by its TRIP ref — the same identifier the\nportal uses at /operators/jobs/{ref}, so one reference works in\nboth surfaces." }, "status": { "type": "string" }, "priority": { "type": "string" }, "sent_at": { "type": [ "string", "null" ] }, "deadline_at": { "type": [ "string", "null" ] }, "responded_at": { "type": [ "string", "null" ] }, "currency_code": { "type": "string" }, "pickup": { "anyOf": [ { "$ref": "#/components/schemas/PlaceResource" }, { "type": "null" } ] }, "dropoff": { "anyOf": [ { "$ref": "#/components/schemas/PlaceResource" }, { "type": "null" } ] }, "pickup_at": { "type": [ "string", "null" ] }, "return_at": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "group_size": { "type": [ "integer", "null" ] }, "vehicle_class": { "type": "string" }, "vehicle_type_hint": { "type": [ "string", "null" ] }, "occasion": { "type": [ "string", "null" ] }, "my_quote": { "anyOf": [ { "description": "Always present on the detail view (the list version only\nincludes it when the relation was eager-loaded).", "$ref": "#/components/schemas/QuoteMoneyResource" }, { "type": "null" } ] }, "use_mode": { "type": "string" }, "trip_type": { "type": "string" }, "duration_minutes": { "type": [ "integer", "null" ] }, "on_call_duration_hours": { "type": [ "integer", "null" ] }, "return_timezone": { "type": [ "string", "null" ] }, "accessibility": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." }, "extras": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." }, "luggage": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." }, "requirements_summary": { "type": [ "string", "null" ] }, "stops": { "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer" }, "role": { "type": "string" }, "place": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "locality": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country_code": { "type": "string" } }, "required": [ "label", "locality", "region", "country_code" ] }, "duration_minutes": { "type": [ "integer", "null" ] } }, "required": [ "sequence", "role", "place", "duration_minutes" ] } }, "platform_fee_pct": { "type": [ "number", "null" ] } }, "required": [ "ref", "status", "priority", "sent_at", "deadline_at", "responded_at", "currency_code", "pickup", "dropoff", "pickup_at", "return_at", "timezone", "group_size", "vehicle_class", "vehicle_type_hint", "occasion", "my_quote", "use_mode", "trip_type", "duration_minutes", "on_call_duration_hours", "return_timezone", "accessibility", "extras", "luggage", "requirements_summary", "stops", "platform_fee_pct" ], "title": "JobDetailResource" }, "JobResource": { "type": "object", "properties": { "ref": { "type": "string", "description": "The job is addressed by its TRIP ref — the same identifier the\nportal uses at /operators/jobs/{ref}, so one reference works in\nboth surfaces." }, "status": { "type": "string" }, "priority": { "type": "string" }, "sent_at": { "type": [ "string", "null" ] }, "deadline_at": { "type": [ "string", "null" ] }, "responded_at": { "type": [ "string", "null" ] }, "currency_code": { "type": "string" }, "pickup": { "anyOf": [ { "$ref": "#/components/schemas/PlaceResource" }, { "type": "null" } ] }, "dropoff": { "anyOf": [ { "$ref": "#/components/schemas/PlaceResource" }, { "type": "null" } ] }, "pickup_at": { "type": [ "string", "null" ] }, "return_at": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "group_size": { "type": [ "integer", "null" ] }, "vehicle_class": { "type": "string" }, "vehicle_type_hint": { "type": [ "string", "null" ] }, "occasion": { "type": [ "string", "null" ] }, "my_quote": { "anyOf": [ { "description": "The operator's own live quote, when they have one. Present so\nan inbox listing can show \"quoted\" without a second call.", "$ref": "#/components/schemas/QuoteMoneyResource" }, { "type": "null" } ] } }, "required": [ "ref", "status", "priority", "sent_at", "deadline_at", "responded_at", "currency_code", "pickup", "dropoff", "pickup_at", "return_at", "timezone", "group_size", "vehicle_class", "vehicle_type_hint", "occasion", "my_quote" ], "title": "JobResource" }, "PayoutResource": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string" }, "currency_code": { "type": "string" }, "amount_minor": { "type": "integer" }, "amount_minor_in_trip_currency": { "type": [ "integer", "null" ] }, "connect_fee_minor": { "type": "integer" }, "connect_fee_payer": { "type": "string" }, "schedule_kind": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "booking_ref": { "type": "string" }, "trip_ref": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "status", "currency_code", "amount_minor", "amount_minor_in_trip_currency", "connect_fee_minor", "connect_fee_payer", "schedule_kind", "scheduled_for", "paid_at", "booking_ref", "trip_ref", "created_at" ], "title": "PayoutResource" }, "PlaceDetailResource": { "type": "object", "properties": { "label": { "type": "string" }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "locality": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ] } }, "required": [ "label", "line1", "line2", "locality", "region", "postal_code", "country_code", "lat", "lng", "timezone" ], "title": "PlaceDetailResource" }, "PlaceResource": { "type": "object", "properties": { "label": { "type": "string" }, "locality": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "country_code": { "type": "string" } }, "required": [ "label", "locality", "region", "country_code" ], "title": "PlaceResource" }, "QuoteActionResource": { "type": "object", "properties": { "result": { "type": "string", "description": "What happened, as a stable code: `submitted`, `revised`,\n`withdrawn`, `unconfirmed`, `declined`, `confirmed`…" }, "message": { "type": [ "string", "null" ] }, "job_ref": { "type": "string", "description": "Echoed so a caller batching several jobs can match an answer to\nthe request that produced it without tracking its own order." }, "quote": { "anyOf": [ { "description": "The quote as it now stands, with every money figure read from\nthe stored columns. Null on actions that leave no quote behind.", "$ref": "#/components/schemas/QuoteMoneyResource" }, { "type": "null" } ] }, "booking_ref": { "type": [ "string", "null" ], "description": "Set only when the action created or confirmed a booking." } }, "required": [ "result", "message", "job_ref", "quote", "booking_ref" ], "title": "QuoteActionResource" }, "QuoteMoneyResource": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "currency_code": { "type": "string" }, "price_total_minor": { "type": "integer" }, "platform_fee_pct": { "type": "number" }, "platform_fee_minor": { "type": "integer" }, "operator_payout_minor": { "type": "integer" }, "vehicle_type": { "type": [ "string", "null" ] }, "seats_offered": { "type": [ "integer", "null" ] }, "availability_confidence": { "type": "string" }, "availability_confirmed_until": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ], "description": "The operator's own note, written by the operator. Not customer\nfree text, so it needs no scrubbing." } }, "required": [ "id", "status", "currency_code", "price_total_minor", "platform_fee_pct", "platform_fee_minor", "operator_payout_minor", "vehicle_type", "seats_offered", "availability_confidence", "availability_confirmed_until", "submitted_at", "accepted_at", "notes" ], "title": "QuoteMoneyResource" }, "WebhookDeliveryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "event": { "type": "string" }, "attempt": { "type": "integer", "description": "The retry counter, not a count of rows: one delivery that the\nreceiver 500s six times is this row with attempt 6." }, "status_code": { "type": [ "integer", "null" ] }, "success": { "type": "boolean" }, "scheduled_at": { "type": "string" }, "delivered_at": { "type": [ "string", "null" ] }, "payload": { "type": [ "object", "array" ], "description": "Free-form JSON as the customer filled it in. The keys are not fixed; read the ones you recognise and ignore the rest." } }, "required": [ "id", "event", "attempt", "status_code", "success", "scheduled_at", "delivered_at", "payload" ], "title": "WebhookDeliveryResource" }, "WebhookResource": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "endpoint_url": { "type": "string" }, "events": { "type": "array", "items": {} }, "status": { "type": "string", "description": "active | paused. A subscription pauses itself after a long run\nof failures rather than being deleted, so the operator can see\nthat it stopped and why." }, "secret_hint": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ] }, "last_failure_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "label", "endpoint_url", "events", "status", "secret_hint", "consecutive_failures", "last_success_at", "last_failure_at", "created_at" ], "title": "WebhookResource" } }, "responses": { "BadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request could not be accepted as sent — for example an `Idempotency-Key` header that is missing or too long. `error.code` is `bad_request` or `idempotency_key_required`." }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The `Idempotency-Key` has already been used for a different request body, or the first attempt with it is still running. `error.code` is `idempotency_key_reused` or `idempotency_in_progress`." }, "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The credential is valid but not allowed to do this — usually a missing ability (`error.code` is `missing_ability`, with the scope in `error.missing_ability`), or an account state that bars the action." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No such resource on your account. A reference belonging to another operator answers 404 rather than 403, so the API cannot be used to find out what exists. `error.code` is `not_found`." }, "RateLimited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too many requests. `error.code` is `rate_limited`; the `Retry-After` header says how long to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "Unauthenticated": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No token, or a token that has expired or been revoked. `error.code` is `unauthenticated`." }, "UnprocessableEntity": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request was understood but refused. Validation failures carry `error.code` `validation_failed` and an `error.fields` map; domain refusals carry their own code." } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A personal access token, sent as `Authorization: Bearer `. Operator keys are minted in the operator portal; the mobile apps exchange a sign-in link or an SMS code for one. Tokens are stored hashed and can be revoked at any time." } } } }