{ "openapi": "3.1.0", "info": { "title": "Conductor Dispatch API", "version": "1.0.0-pilot", "description": "Complete reference for the current dedicated Azure Functions HTTP surface. Single-organization RLV pilot; not a claim of broker approval, clinical compliance, outbound webhook delivery, or native-app release. USD manual receivables ledger; no card processing." }, "servers": [ { "url": "https://conductorrlv-prod-api-lbgams3snpcdy.azurewebsites.net/api/v1", "description": "Conductor dedicated production API" } ], "security": [ { "Bearer": [] } ], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Entra v2 access token or scoped cnd_ integration secret", "description": "Microsoft single-tenant PKCE app with access_as_user scope, or server-held API key. Tenant, audience, role, organization and driver boundary enforced." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": true }, "Entity": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "additionalProperties": true }, "IdempotentAction": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." } }, "required": [ "idempotencyKey", "expectedVersion" ], "additionalProperties": true }, "Driver": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "contractIds": { "type": "array", "items": { "type": "string" } }, "entraObjectId": { "type": "string", "format": "uuid" }, "homeBaseAddress": { "type": "string" }, "startLocationAt": { "type": [ "string", "null" ], "format": "date-time" }, "availableFrom": { "type": [ "string", "null" ], "format": "date-time" }, "availableTo": { "type": [ "string", "null" ], "format": "date-time" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "required": [ "name" ], "additionalProperties": true }, "Vehicle": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "capacity": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000, "description": "Confirmed usable passenger capacity excluding driver. Unknown/null is allowed only for an inactive staged vehicle. Activating requires a positive integer; the server validates the merged record." }, "licensePlate": { "type": "string" }, "vin": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "contractIds": { "type": "array", "items": { "type": "string" } }, "homeBaseAddress": { "type": "string" }, "startLocationAt": { "type": [ "string", "null" ], "format": "date-time" }, "routingDimensions": { "$ref": "#/components/schemas/VehicleDimensions" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true }, "wheelchairPositions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20, "description": "Verified physical positions INSIDE the total passenger limit, not additional passenger capacity. Null/omitted means unverified and cannot satisfy this mobility requirement. Layout compatibility still requires operator verification." }, "stretcherPositions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20, "description": "Verified physical positions INSIDE the total passenger limit, not additional passenger capacity. Null/omitted means unverified and cannot satisfy this mobility requirement. Layout compatibility still requires operator verification." } }, "required": [ "name" ], "additionalProperties": true }, "VehicleDimensions": { "type": "object", "properties": { "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 10, "description": "Meters" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 5, "description": "Meters" }, "length": { "type": "number", "exclusiveMinimum": 0, "maximum": 40, "description": "Meters" }, "weight": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Kilograms; use verified dimensions/operating weight." } }, "additionalProperties": true }, "Passenger": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "phone": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "required": [ "name" ], "additionalProperties": true }, "Facility": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "address": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "required": [ "name" ], "additionalProperties": true }, "Payer": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "reference": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "required": [ "name" ], "additionalProperties": true }, "Contract": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive", "expired", "suspended" ] }, "payerId": { "type": "string" }, "state": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "program": { "type": "string" }, "externalContractId": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "required": [ "name" ], "additionalProperties": true }, "LegacyBillingDraft": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "const": "draft" }, "amount": { "type": "number", "minimum": 0, "description": "Legacy dollars field; not an issued invoice or integer-cent ledger." }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true } }, "required": [ "name", "amount" ], "additionalProperties": true }, "Trip": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "serviceDate": { "type": "string", "format": "date" }, "passengerName": { "type": "string", "maxLength": 500 }, "pickup": { "type": "string", "maxLength": 500 }, "dropoff": { "type": "string", "maxLength": 500 }, "pickupAt": { "type": "string", "format": "date-time", "description": "ISO timestamp with Z or explicit UTC offset; required for dispatch and alerts." }, "scheduledStartAt": { "type": "string", "format": "date-time" }, "estimatedDurationMinutes": { "type": "number", "exclusiveMinimum": 0, "description": "Reserved service minutes. Routed assignment raises it to the calculated minimum." }, "capacityNeeded": { "type": "integer", "minimum": 1 }, "requiredCapabilities": { "type": "array", "items": { "type": "string" } }, "contractId": { "type": "string" }, "payerId": { "type": "string" }, "passengerId": { "type": "string" }, "facilityId": { "type": "string" }, "pickupArea": { "type": "string" }, "externalTripId": { "type": "string" }, "driverId": { "type": "string", "readOnly": true }, "vehicleId": { "type": "string", "readOnly": true }, "status": { "type": "string", "readOnly": true, "enum": [ "scheduled", "en_route", "arrived", "picked_up", "completed", "cancelled" ] }, "routing": { "type": "object", "properties": {}, "additionalProperties": true, "readOnly": true }, "eventReceipts": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "readOnly": true }, "wheelchairPositionsNeeded": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Mobility occupants count within capacityNeeded. A required wheelchair/stretcher capability implies at least one position even when this count is omitted/zero. Counts imply the corresponding required vehicle and driver qualification; assignment cannot exceed verified positions." }, "stretcherPositionsNeeded": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Mobility occupants count within capacityNeeded. A required wheelchair/stretcher capability implies at least one position even when this count is omitted/zero. Counts imply the corresponding required vehicle and driver qualification; assignment cannot exceed verified positions." } }, "required": [ "serviceDate", "passengerName", "pickup", "dropoff" ], "additionalProperties": true }, "RecurringTrip": { "allOf": [ { "$ref": "#/components/schemas/Trip" }, { "type": "object", "properties": { "recurrence": { "type": "object", "properties": { "seriesId": { "type": "string", "description": "Reuse the returned series ID here on a retry." }, "weekdays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "minItems": 1, "description": "Sunday=0 through Saturday=6." }, "untilDate": { "type": "string", "format": "date" }, "maxOccurrences": { "type": "integer" }, "timeZone": { "type": "string", "default": "America/New_York" } }, "required": [ "weekdays" ], "additionalProperties": true } }, "required": [ "recurrence" ], "additionalProperties": true } ] }, "TripEvent": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "en_route", "arrived", "picked_up", "completed", "cancelled" ] }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "occurredAt": { "type": "string", "format": "date-time" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "action", "idempotencyKey" ], "additionalProperties": true }, "TripOperation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inspection", "odometer", "receipt" ] }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "occurredAt": { "type": "string", "format": "date-time" }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "type", "idempotencyKey" ], "additionalProperties": true }, "UploadIntent": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "type": { "type": "string", "enum": [ "inspection_photo", "receipt_attachment" ] }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "application/pdf" ] }, "byteLength": { "type": "integer", "minimum": 1, "maximum": 10485760 } }, "required": [ "idempotencyKey", "type", "contentType", "byteLength" ], "additionalProperties": true }, "Assignment": { "type": "object", "properties": { "tripId": { "type": "string" }, "driverId": { "type": "string" }, "vehicleId": { "type": "string" }, "bufferMinutes": { "type": "number", "minimum": 0, "default": 10 }, "manualRoutingOverrideReason": { "type": "string", "minLength": 12, "description": "Explicit administrator exception requiring routes:override; bypasses traffic/positioning checks and is audited." } }, "required": [ "tripId", "driverId", "vehicleId" ], "additionalProperties": true }, "RouteEstimate": { "type": "object", "properties": { "origin": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Coordinates" } ] }, "destination": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Coordinates" } ] }, "departAt": { "type": "string", "format": "date-time" }, "arriveAt": { "type": "string", "format": "date-time", "description": "Use arriveAt OR departAt, never both." }, "vehicleSpec": { "$ref": "#/components/schemas/VehicleDimensions" } }, "required": [ "origin", "destination" ], "additionalProperties": true }, "Coordinates": { "type": "object", "properties": { "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "address": { "type": "string" } }, "required": [ "longitude", "latitude" ], "additionalProperties": true }, "RouteQuote": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "durationMs": { "type": "number", "minimum": 0 }, "distanceMeters": { "type": "number", "minimum": 0 }, "trafficAware": { "type": "boolean" }, "cached": { "type": "boolean" }, "calculatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "origin": { "type": "object", "properties": {}, "additionalProperties": true }, "destination": { "type": "object", "properties": {}, "additionalProperties": true }, "advisory": { "type": "string" } }, "additionalProperties": true }, "OperationsSettings": { "type": "object", "properties": { "depotAddress": { "type": "string", "maxLength": 350 }, "timeZone": { "type": "string", "default": "America/New_York" }, "loadingMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "default": 10 }, "unloadingMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "default": 10 }, "routingSafetyPercent": { "type": "integer", "minimum": 0, "maximum": 240, "default": 20 }, "returnToDepot": { "type": "boolean", "default": false }, "sellerName": { "type": "string" }, "sellerAddress": { "type": "string" }, "sellerEmail": { "type": "string", "format": "email" }, "sellerPhone": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "version": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409.", "readOnly": true }, "companyName": { "type": "string", "maxLength": 160 }, "companyWebsite": { "type": "string", "format": "uri", "description": "http or https URL; empty string clears the optional value." } }, "additionalProperties": true }, "InvoiceLine": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 180 }, "quantity": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,3})?$" }, { "type": "number", "exclusiveMinimum": 0 } ], "description": "Positive quantity, up to three fractional places." }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "taxBasisPoints": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "100 basis points = 1%." }, "tripId": { "type": "string" } }, "required": [ "description", "quantity", "unitAmountCents" ], "additionalProperties": true }, "InvoiceDraft": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "billToName": { "type": "string", "minLength": 1, "maxLength": 240 }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "currency": { "type": "string", "const": "USD" }, "payerId": { "type": [ "string", "null" ] }, "contractId": { "type": [ "string", "null" ] }, "reference": { "type": "string" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" }, "minItems": 1, "maxItems": 100 } }, "required": [ "idempotencyKey", "billToName", "issueDate", "dueDate", "lineItems" ], "additionalProperties": true }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "status": { "type": "string", "enum": [ "draft", "issued", "void" ] }, "billToName": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "payerId": { "type": [ "string", "null" ] }, "contractId": { "type": [ "string", "null" ] }, "currency": { "type": "string", "const": "USD" }, "reference": { "type": "string" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "subtotalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "taxCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "paidCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "balanceCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "paymentStatus": { "type": "string", "enum": [ "draft", "unpaid", "part_paid", "paid", "void" ] }, "payments": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "seller": { "type": "object", "properties": {}, "additionalProperties": true }, "history": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true }, "Receipt": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "amountCents": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "receivedDate": { "type": "string", "format": "date" }, "reference": { "type": "string", "minLength": 1, "maxLength": 240 }, "method": { "type": "string" } }, "required": [ "idempotencyKey", "expectedVersion", "amountCents", "receivedDate", "reference", "method" ], "additionalProperties": true }, "Cost": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "description": { "type": "string" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "incurredDate": { "type": "string", "format": "date" }, "category": { "type": "string" }, "contractId": { "type": [ "string", "null" ] }, "tripId": { "type": "string" }, "reference": { "type": "string" }, "currency": { "type": "string", "const": "USD" } }, "required": [ "idempotencyKey", "description", "amountCents", "incurredDate", "category" ], "additionalProperties": true }, "FinancialSummary": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "through": { "type": "string", "format": "date" }, "revenueCents": { "type": "integer", "description": "Signed integer USD cents. A later-period void can produce negative recognized revenue/tax." }, "taxCents": { "type": "integer", "description": "Signed integer USD cents. A later-period void can produce negative recognized revenue/tax." }, "cashReceivedCents": { "type": "integer" }, "costCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "contributionCents": { "type": "integer" }, "outstandingCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Integer USD cents, never floating-point dollars." }, "aging": { "type": "object", "properties": {}, "additionalProperties": true }, "byContract": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "basis": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "Destination": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "audienceEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 25 }, "authMode": { "type": "string", "enum": [ "managed_identity", "secret_url" ], "default": "managed_identity" }, "teamsWorkflowUrl": { "type": "string", "writeOnly": true, "format": "uri", "description": "Private HTTPS Logic Apps/Power Platform Workflow URL. Stored in Key Vault; never returned." }, "enabled": { "type": "boolean", "default": false }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "confirmedReceipt": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409.", "readOnly": true }, "configured": { "type": "boolean", "readOnly": true }, "lastTestAcceptedAt": { "type": "string", "format": "date-time", "readOnly": true }, "confirmedReceiptAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "email" ], "additionalProperties": true }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "outboxId": { "type": "string" }, "destinationId": { "type": "string" }, "tripId": { "type": [ "string", "null" ] }, "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "sending", "accepted", "blocked", "unknown", "retry_wait" ] }, "channel": { "type": "string", "const": "teams" }, "at": { "type": "string", "format": "date-time" }, "attempt": { "type": "integer" }, "httpStatus": { "type": "integer" }, "error": { "type": "string" }, "retryAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "ShiftRequest": { "type": "object", "properties": { "id": { "type": "string" }, "tripId": { "type": "string" }, "driverId": { "type": "string" }, "scheduledStartAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "requested", "acknowledged", "declined", "withdrawn" ] }, "note": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "reviewNote": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409.", "readOnly": true }, "serviceDate": { "type": "string", "format": "date" }, "history": { "type": "array", "readOnly": true, "items": { "type": "object", "additionalProperties": true }, "description": "Version/status/actor history committed atomically with the request." } }, "additionalProperties": true }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "revoked": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Returned once by POST only. Keep on trusted servers; never in website JavaScript or logs." } }, "additionalProperties": true }, "CommunicationStage": { "type": "object", "required": [ "id", "label", "leadMinutes", "color", "enabled" ], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "label": { "type": "string", "maxLength": 60 }, "leadMinutes": { "type": "integer", "minimum": 1, "maximum": 44640 }, "color": { "type": "string", "enum": [ "yellow", "red" ] }, "enabled": { "type": "boolean" } } }, "CommunicationSettings": { "type": "object", "properties": { "id": { "type": "string", "const": "communications" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." }, "teamsEnabled": { "type": "boolean" }, "smsEnabled": { "type": "boolean", "const": false }, "title": { "type": "string", "maxLength": 160 }, "bodyTemplate": { "type": "string", "maxLength": 500, "description": "Generic only. Supported placeholders: {{stage}}, {{start}}, {{reference}}. No patient information." }, "stages": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/CommunicationStage" } } } }, "SetupState": { "type": "object", "properties": { "id": { "type": "string", "const": "setup" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." }, "step": { "type": "string", "enum": [ "company", "locations", "fleet", "contracts", "communications", "review" ] }, "reviewedSteps": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "object", "additionalProperties": { "type": "boolean" } }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "missing": { "type": "array", "items": { "type": "string" } }, "completedAt": { "type": "string", "format": "date-time" }, "smsEnabled": { "type": "boolean", "const": false }, "operationalAcceptanceRequired": { "type": "boolean", "const": true }, "brokerApprovalConfirmed": { "type": "boolean", "const": false }, "readinessIssues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "count": { "type": "integer", "minimum": 1 }, "resource": { "type": "string" } } }, "description": "Configuration gaps only; absence of issues does not establish operational acceptance." }, "microsoftRoleVerificationRequired": { "type": "boolean", "const": true } } }, "BackupProof": { "type": "object", "properties": { "organizationId": { "type": "string" }, "name": { "type": "string", "description": "Private object name, not a download URL." }, "status": { "type": "string", "enum": [ "verified", "verified_existing" ] }, "capturedAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordCount": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "versionId": { "type": "string" }, "initiatedBy": { "type": "string" } } }, "BackupStatus": { "type": "object", "properties": { "configured": { "type": "boolean" }, "scheduleUtc": { "type": "string", "const": "04:30 daily" }, "consistency": { "type": "string", "const": "logical_export_not_transactional_point_in_time" }, "attachmentFilesIncluded": { "type": "boolean", "const": false }, "credentialsIncluded": { "type": "boolean", "const": false }, "lastVerified": { "oneOf": [ { "$ref": "#/components/schemas/BackupProof" }, { "type": "null" } ] } } } } }, "paths": { "/health": { "get": { "operationId": "get__health", "summary": "Public service liveness", "tags": [ "health" ], "description": "Raw {ok,service}; not the standard data envelope. Does not prove routing, Teams, broker feeds or billing acceptance.", "x-required-scopes": [], "x-scope-match": "any", "security": [], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "servers": [ { "url": "https://conductorrlv-prod-api-lbgams3snpcdy.azurewebsites.net/api" } ] } }, "/me": { "get": { "operationId": "get__me", "summary": "Current organization, scopes and linked driver", "tags": [ "me" ], "description": "", "x-required-scopes": [], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "organizationId": { "type": "string" }, "authentication": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "driverId": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/drivers/me": { "get": { "operationId": "get__drivers_me", "summary": "Current linked driver", "tags": [ "drivers" ], "description": "Requires a linked active driver identity, not just an administrator role.", "x-required-scopes": [], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/drivers": { "get": { "operationId": "get__drivers", "summary": "List drivers", "tags": [ "drivers" ], "description": "", "x-required-scopes": [ "drivers:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Driver" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__drivers", "summary": "Create drivers record", "tags": [ "drivers" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned. Resource access: contractIds must reference this organization’s contracts. An empty list means unrestricted, not confirmed compliance. Creating/changing/removing a driver entraObjectId requires identity:write or administrator authority; unchanged identity values are allowed in routine edits.", "x-required-scopes": [ "drivers:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Driver" } } } } } }, "/drivers/{id}": { "get": { "operationId": "get__drivers__id_", "summary": "Get one drivers record", "tags": [ "drivers" ], "description": "", "x-required-scopes": [ "drivers:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__drivers__id_", "summary": "Edit or retire drivers record", "tags": [ "drivers" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "drivers:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "contractIds": { "type": "array", "items": { "type": "string" } }, "entraObjectId": { "type": "string", "format": "uuid" }, "homeBaseAddress": { "type": "string" }, "startLocationAt": { "type": [ "string", "null" ], "format": "date-time" }, "availableFrom": { "type": [ "string", "null" ], "format": "date-time" }, "availableTo": { "type": [ "string", "null" ], "format": "date-time" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } }, "required": [], "additionalProperties": true } } } } } }, "/vehicles": { "get": { "operationId": "get__vehicles", "summary": "List vehicles", "tags": [ "vehicles" ], "description": "", "x-required-scopes": [ "vehicles:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__vehicles", "summary": "Create vehicles record", "tags": [ "vehicles" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned. Resource access: contractIds must reference this organization’s contracts. An empty list means unrestricted, not confirmed compliance. Creating/changing/removing a driver entraObjectId requires identity:write or administrator authority; unchanged identity values are allowed in routine edits.", "x-required-scopes": [ "vehicles:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle", "required": [], "allOf": [ { "$comment": "conductor_vehicle_capacity", "anyOf": [ { "required": [ "status" ], "properties": { "status": { "enum": [ "inactive" ] } } }, { "required": [ "capacity" ], "properties": { "capacity": { "type": "integer", "minimum": 1, "maximum": 1000 } } } ] } ] } } } } } }, "/vehicles/{id}": { "get": { "operationId": "get__vehicles__id_", "summary": "Get one vehicles record", "tags": [ "vehicles" ], "description": "", "x-required-scopes": [ "vehicles:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__vehicles__id_", "summary": "Edit or retire vehicles record", "tags": [ "vehicles" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "vehicles:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "capacity": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000, "description": "Confirmed usable passenger capacity excluding driver. Unknown/null is allowed only for an inactive staged vehicle. Activating requires a positive integer; the server validates the merged record." }, "licensePlate": { "type": "string" }, "vin": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "contractIds": { "type": "array", "items": { "type": "string" } }, "homeBaseAddress": { "type": "string" }, "startLocationAt": { "type": [ "string", "null" ], "format": "date-time" }, "routingDimensions": { "$ref": "#/components/schemas/VehicleDimensions" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." }, "wheelchairPositions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20, "description": "Verified physical positions INSIDE the total passenger limit, not additional passenger capacity. Null/omitted means unverified and cannot satisfy this mobility requirement. Layout compatibility still requires operator verification." }, "stretcherPositions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 20, "description": "Verified physical positions INSIDE the total passenger limit, not additional passenger capacity. Null/omitted means unverified and cannot satisfy this mobility requirement. Layout compatibility still requires operator verification." } }, "required": [], "additionalProperties": true } } } } } }, "/passengers": { "get": { "operationId": "get__passengers", "summary": "List passengers", "tags": [ "passengers" ], "description": "", "x-required-scopes": [ "passengers:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Passenger" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__passengers", "summary": "Create passengers record", "tags": [ "passengers" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned.", "x-required-scopes": [ "passengers:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Passenger" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passenger" } } } } } }, "/passengers/{id}": { "get": { "operationId": "get__passengers__id_", "summary": "Get one passengers record", "tags": [ "passengers" ], "description": "", "x-required-scopes": [ "passengers:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Passenger" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__passengers__id_", "summary": "Edit or retire passengers record", "tags": [ "passengers" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "passengers:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Passenger" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "phone": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } }, "required": [], "additionalProperties": true } } } } } }, "/facilities": { "get": { "operationId": "get__facilities", "summary": "List facilities", "tags": [ "facilities" ], "description": "", "x-required-scopes": [ "facilities:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Facility" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__facilities", "summary": "Create facilities record", "tags": [ "facilities" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned.", "x-required-scopes": [ "facilities:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Facility" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facility" } } } } } }, "/facilities/{id}": { "get": { "operationId": "get__facilities__id_", "summary": "Get one facilities record", "tags": [ "facilities" ], "description": "", "x-required-scopes": [ "facilities:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Facility" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__facilities__id_", "summary": "Edit or retire facilities record", "tags": [ "facilities" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "facilities:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Facility" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "address": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } }, "required": [], "additionalProperties": true } } } } } }, "/payers": { "get": { "operationId": "get__payers", "summary": "List payers", "tags": [ "payers" ], "description": "", "x-required-scopes": [ "payers:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payer" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__payers", "summary": "Create payers record", "tags": [ "payers" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned.", "x-required-scopes": [ "payers:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payer" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payer" } } } } } }, "/payers/{id}": { "get": { "operationId": "get__payers__id_", "summary": "Get one payers record", "tags": [ "payers" ], "description": "", "x-required-scopes": [ "payers:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payer" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__payers__id_", "summary": "Edit or retire payers record", "tags": [ "payers" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "payers:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payer" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "reference": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } }, "required": [], "additionalProperties": true } } } } } }, "/contracts": { "get": { "operationId": "get__contracts", "summary": "List contracts", "tags": [ "contracts" ], "description": "", "x-required-scopes": [ "contracts:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__contracts", "summary": "Create contracts record", "tags": [ "contracts" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned.", "x-required-scopes": [ "contracts:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contract" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } } } }, "/contracts/{id}": { "get": { "operationId": "get__contracts__id_", "summary": "Get one contracts record", "tags": [ "contracts" ], "description": "", "x-required-scopes": [ "contracts:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contract" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__contracts__id_", "summary": "Edit or retire contracts record", "tags": [ "contracts" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "contracts:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contract" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "active", "inactive", "expired", "suspended" ] }, "payerId": { "type": "string" }, "state": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "program": { "type": "string" }, "externalContractId": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } }, "required": [], "additionalProperties": true } } } } } }, "/billing-records": { "get": { "operationId": "get__billing_records", "summary": "List billing-records", "tags": [ "billing-records" ], "description": "", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LegacyBillingDraft" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__billing_records", "summary": "Create billing-records record", "tags": [ "billing-records" ], "description": "No general create idempotency guarantee. If response is lost, query/reconcile before creating another record. Organization and ID are server assigned.", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LegacyBillingDraft" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyBillingDraft" } } } } } }, "/billing-records/{id}": { "get": { "operationId": "get__billing_records__id_", "summary": "Get one billing-records record", "tags": [ "billing-records" ], "description": "", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LegacyBillingDraft" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__billing_records__id_", "summary": "Edit or retire billing-records record", "tags": [ "billing-records" ], "description": "Retire with status inactive. No DELETE endpoint; preserve IDs/history. Contract and driver-identity uniqueness are organization scoped. Versioned edits: send expectedVersion from the latest GET to reject stale writes (409). The web editor always sends it. Omitting it preserves legacy last-writer behavior without conflict protection.", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LegacyBillingDraft" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "const": "draft" }, "amount": { "type": "number", "minimum": 0, "description": "Legacy dollars field; not an issued invoice or integer-cent ledger." }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } }, "required": [], "additionalProperties": true } } } } } }, "/identity-mappings": { "get": { "operationId": "get__identity_mappings", "summary": "List explicit identity mappings", "tags": [ "identity-mappings" ], "description": "", "x-required-scopes": [ "identity:read", "keys:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__identity_mappings", "summary": "Bind tenant user to the current organization", "tags": [ "identity-mappings" ], "description": "tenantId defaults to configured Conductor tenant. Does not create Microsoft users, grant app roles, or change MFA.", "x-required-scopes": [ "identity:write", "keys:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string" }, "entraObjectId": { "type": "string" } }, "required": [ "entraObjectId" ], "additionalProperties": true } } } } } }, "/api-keys": { "get": { "operationId": "get__api_keys", "summary": "List key metadata, never secrets", "tags": [ "api-keys" ], "description": "", "x-required-scopes": [ "keys:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__api_keys", "summary": "Create scoped integration key; secret shown once", "tags": [ "api-keys" ], "description": "Defaults to trips:read. Non-wildcard issuers cannot mint broader scopes than their own. Keys currently do not auto-expire; explicitly revoke and rotate. Never store in public frontend code.", "x-required-scopes": [ "keys:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": true } } } } } }, "/api-keys/{id}": { "patch": { "operationId": "patch__api_keys__id_", "summary": "Revoke integration key", "tags": [ "api-keys" ], "description": "", "x-required-scopes": [ "keys:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true } }, "required": [ "revoked" ], "additionalProperties": true } } } } } }, "/trips": { "get": { "operationId": "get__trips", "summary": "List authorized trips", "tags": [ "trips" ], "description": "Driver-bound credentials see only their assigned trips, even with wildcard scopes.", "x-required-scopes": [ "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "contractId", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "post__trips", "summary": "Create scheduled trip", "tags": [ "trips" ], "description": "Dispatcher/admin only. driverId/vehicleId/assignmentStatus cannot be set here. Query/reconcile after uncertain creation; no automatic create replay.", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trip" } } } } } }, "/trips/{id}": { "get": { "operationId": "get__trips__id_", "summary": "Read authorized trip", "tags": [ "trips" ], "description": "", "x-required-scopes": [ "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__trips__id_", "summary": "Edit trip before assignment", "tags": [ "trips" ], "description": "Dispatcher/admin only. Assignment/status use their dedicated endpoints. Assigned routing/timing changes require unassign/review/reassign.", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "organizationId": { "type": "string", "readOnly": true }, "serviceDate": { "type": "string", "format": "date" }, "passengerName": { "type": "string", "maxLength": 500 }, "pickup": { "type": "string", "maxLength": 500 }, "dropoff": { "type": "string", "maxLength": 500 }, "pickupAt": { "type": "string", "format": "date-time", "description": "ISO timestamp with Z or explicit UTC offset; required for dispatch and alerts." }, "scheduledStartAt": { "type": "string", "format": "date-time" }, "estimatedDurationMinutes": { "type": "number", "exclusiveMinimum": 0, "description": "Reserved service minutes. Routed assignment raises it to the calculated minimum." }, "capacityNeeded": { "type": "integer", "minimum": 1 }, "requiredCapabilities": { "type": "array", "items": { "type": "string" } }, "contractId": { "type": "string" }, "payerId": { "type": "string" }, "passengerId": { "type": "string" }, "facilityId": { "type": "string" }, "pickupArea": { "type": "string" }, "externalTripId": { "type": "string" }, "driverId": { "type": "string", "readOnly": true }, "vehicleId": { "type": "string", "readOnly": true }, "status": { "type": "string", "readOnly": true, "enum": [ "scheduled", "en_route", "arrived", "picked_up", "completed", "cancelled" ] }, "routing": { "type": "object", "properties": {}, "additionalProperties": true, "readOnly": true }, "eventReceipts": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "readOnly": true }, "wheelchairPositionsNeeded": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Mobility occupants count within capacityNeeded. A required wheelchair/stretcher capability implies at least one position even when this count is omitted/zero. Counts imply the corresponding required vehicle and driver qualification; assignment cannot exceed verified positions." }, "stretcherPositionsNeeded": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Mobility occupants count within capacityNeeded. A required wheelchair/stretcher capability implies at least one position even when this count is omitted/zero. Counts imply the corresponding required vehicle and driver qualification; assignment cannot exceed verified positions." } }, "required": [], "additionalProperties": true } } } } } }, "/trips/recurring": { "post": { "operationId": "post__trips_recurring", "summary": "Create weekday series with local-time DST handling", "tags": [ "trips" ], "description": "Reuse returned seriesId to avoid recreating its service dates. Maximum window 366 days; no assignment copied. Ambiguous/nonexistent daylight-saving clock times require review.", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "seriesId": { "type": "string" }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "skipped": { "type": "array", "items": { "type": "string", "format": "date" } } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringTrip" } } } } } }, "/trips/{id}/events": { "post": { "operationId": "post__trips__id__events", "summary": "Advance trip state with atomic canonical event receipt", "tags": [ "trips" ], "description": "scheduled → en_route → arrived → picked_up → completed. Dispatcher may cancel; drivers cannot cancel. Same idempotency key with changed payload returns 409.", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trip": { "$ref": "#/components/schemas/Trip" }, "event": { "type": "object", "properties": {}, "additionalProperties": true }, "replayed": { "type": "boolean" } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripEvent" } } } } } }, "/trips/{id}/operations": { "get": { "operationId": "get__trips__id__operations", "summary": "List inspection, odometer and receipt records", "tags": [ "trips" ], "description": "", "x-required-scopes": [ "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "post__trips__id__operations", "summary": "Record driver operation once", "tags": [ "trips" ], "description": "", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripOperation" } } } } } }, "/trips/{id}/attachments": { "get": { "operationId": "get__trips__id__attachments", "summary": "List private attachment metadata", "tags": [ "trips" ], "description": "", "x-required-scopes": [ "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/trips/{id}/attachments/upload-intents": { "post": { "operationId": "post__trips__id__attachments_upload_intents", "summary": "Request one short-lived direct Blob upload", "tags": [ "trips" ], "description": "Upload URL lasts 10 minutes. PUT bytes to it with x-ms-blob-type:BlockBlob and the declared Content-Type; do not send the Conductor bearer token to Blob. Keep the same intent for retries.", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uploadIntentId": { "type": "string" }, "uploadUrl": { "type": "string" }, "blobName": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "contentType": { "type": "string" } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadIntent" } } } } } }, "/trips/{id}/attachments/complete": { "post": { "operationId": "post__trips__id__attachments_complete", "summary": "Verify upload and commit deterministic attachment", "tags": [ "trips" ], "description": "Checks actual byte length, MIME and file signature. Does not constitute malware scanning.", "x-required-scopes": [ "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadIntentId": { "type": "string" } }, "required": [ "uploadIntentId" ], "additionalProperties": true } } } } } }, "/trips/{id}/attachments/{attachmentId}/read-intents": { "post": { "operationId": "post__trips__id__attachments__attachmentId__read_intents", "summary": "Get temporary protected download link", "tags": [ "trips" ], "description": "Five-minute read URL. Do not publish or log it.", "x-required-scopes": [ "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attachmentId": { "type": "string" }, "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/dispatch/board": { "get": { "operationId": "get__dispatch_board", "summary": "Date and optional contract dispatch board", "tags": [ "dispatch" ], "description": "", "x-required-scopes": [ "dispatch:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "contractId", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/dispatch/plan": { "post": { "operationId": "post__dispatch_plan", "summary": "Preview feasible assignments; never auto-commit", "tags": [ "dispatch" ], "description": "Up to ten trips per batch and bounded candidate/time search. Uses active resources, capabilities, contract restrictions, traffic, loading/unloading, start locations, inter-trip positioning and availability. Confirm individual proposals. Use a 150-second client timeout.", "x-required-scopes": [ "dispatch:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "unassigned": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "assumptions": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "contractId": { "type": "string" }, "bufferMinutes": { "type": "number", "minimum": 0 }, "manualRoutingOverrideReason": { "type": "string" } }, "required": [ "date" ], "additionalProperties": true } } } } } }, "/dispatch/assignments": { "post": { "operationId": "post__dispatch_assignments", "summary": "Revalidate and commit one assignment under organization lease", "tags": [ "dispatch" ], "description": "Top-level proposal also returned. Same existing pairing replays. Different driver/van start locations require confirmed repositioning; no transport is silently invented. Admin-only manualRoutingOverrideReason is an audited exception, not verified routing. Partial reservations: a driver-only or van-only scheduled reservation can be completed only by keeping its existing resource unchanged. All availability, capability, contract and configured travel checks still apply. A different existing resource returns 409; unassign first to change it.", "x-required-scopes": [ "dispatch:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" } } } } } }, "/dispatch/unassign": { "post": { "operationId": "post__dispatch_unassign", "summary": "Release a scheduled assignment", "tags": [ "dispatch" ], "description": "Include expected IDs to prevent a stale page releasing another dispatcher’s changed pairing. Started trips require manual dispatch review.", "x-required-scopes": [ "dispatch:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tripId": { "type": "string" }, "expectedDriverId": { "type": "string" }, "expectedVehicleId": { "type": "string" } }, "required": [ "tripId" ], "additionalProperties": true } } } } } }, "/shift-requests/available": { "get": { "operationId": "get__shift_requests_available", "summary": "Minimal non-patient open-shift feed", "tags": [ "shift-requests" ], "description": "Minimal staffing feed, including van-only reservations. Omits passenger names, exact addresses and free-text pickup areas. Driver qualification/contract filtering applies.", "x-required-scopes": [ "dispatch:read", "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ] } }, "/shift-requests": { "get": { "operationId": "get__shift_requests", "summary": "List shift requests", "tags": [ "shift-requests" ], "description": "Driver-bound callers see only their own requests.", "x-required-scopes": [ "dispatch:read", "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShiftRequest" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trips/{id}/shift-requests": { "post": { "operationId": "post__trips__id__shift_requests", "summary": "Request this scheduled departure", "tags": [ "trips" ], "description": "Request an unassigned scheduled departure; a vehicle may already be reserved. Active qualifications and contract approval are checked. Driver identity is bound to the authenticated driver. A retry returns the existing request (200); a new/reopened cycle returns 201. This silences only the matching departure alarm and never assigns a driver/van.", "x-required-scopes": [ "dispatch:write", "trips:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ShiftRequest" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ShiftRequest" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "driverId": { "type": "string", "description": "Dispatcher use only; driver credentials cannot impersonate another driver." }, "note": { "type": "string", "maxLength": 1000 } } } } } } } }, "/shift-requests/{id}": { "patch": { "operationId": "patch__shift_requests__id_", "summary": "Review shift request", "tags": [ "shift-requests" ], "description": "Dispatcher review only. Acknowledgement is not assignment. Supply expectedVersion and a reviewNote (3–300 characters). Stale versions or acknowledgement of a rescheduled/assigned departure return 409. Decline/withdraw can release suppression if no other active interest/acknowledgement exists.", "x-required-scopes": [ "dispatch:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ShiftRequest" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "reviewNote", "expectedVersion" ], "additionalProperties": false, "properties": { "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." }, "status": { "type": "string", "enum": [ "acknowledged", "declined", "withdrawn" ] }, "reviewNote": { "type": "string", "minLength": 3, "maxLength": 300 } } } } } } } }, "/settings/operations": { "get": { "operationId": "get__settings_operations", "summary": "Read depot, buffer and seller settings", "tags": [ "settings" ], "description": "", "x-required-scopes": [ "settings:read", "dispatch:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OperationsSettings" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patch__settings_operations", "summary": "Versioned organization settings update", "tags": [ "settings" ], "description": "expectedVersion required. Only documented fields accepted. Seller details are snapshotted on invoice issue, not retroactively changed.", "x-required-scopes": [ "settings:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OperationsSettings" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "depotAddress": { "type": "string", "maxLength": 350 }, "timeZone": { "type": "string", "default": "America/New_York" }, "loadingMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "default": 10 }, "unloadingMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "default": 10 }, "routingSafetyPercent": { "type": "integer", "minimum": 0, "maximum": 240, "default": 20 }, "returnToDepot": { "type": "boolean", "default": false }, "sellerName": { "type": "string" }, "sellerAddress": { "type": "string" }, "sellerEmail": { "type": "string", "format": "email" }, "sellerPhone": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "version": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409.", "readOnly": true }, "companyName": { "type": "string", "maxLength": 160 }, "companyWebsite": { "type": "string", "format": "uri", "description": "http or https URL; empty string clears the optional value." } }, "additionalProperties": true, "required": [ "expectedVersion" ] } } } } } }, "/routes/estimate": { "post": { "operationId": "post__routes_estimate", "summary": "Traffic-aware cached route quote", "tags": [ "routes" ], "description": "Azure Maps managed identity. Five-minute cache. Global application cap defaults to 800 estimates/month including failed provider attempts. Confirm ambiguous addresses or use verified coordinates; never invent coordinates. Forecast, not guaranteed arrival.", "x-required-scopes": [ "routes:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RouteQuote" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteEstimate" } } } } } }, "/billing/invoices": { "get": { "operationId": "get__billing_invoices", "summary": "List posted/draft invoices", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "contractId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "operationId": "post__billing_invoices", "summary": "Create cent-accurate invoice draft", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraft" } } } } } }, "/billing/invoices/{id}": { "get": { "operationId": "get__billing_invoices__id_", "summary": "Get invoice and receipt history", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "patch__billing_invoices__id_", "summary": "Edit draft only, with version check", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "billToName": { "type": "string", "minLength": 1, "maxLength": 240 }, "issueDate": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date" }, "currency": { "type": "string", "const": "USD" }, "payerId": { "type": [ "string", "null" ] }, "contractId": { "type": [ "string", "null" ] }, "reference": { "type": "string" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" }, "minItems": 1, "maxItems": 100 }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." } }, "required": [ "expectedVersion" ], "additionalProperties": true } } } } } }, "/billing/invoices/{id}/issue": { "post": { "operationId": "post__billing_invoices__id__issue", "summary": "Issue immutable numbered invoice", "tags": [ "billing" ], "description": "Requires sellerName configured, issue date not in future, and no already-billed trip. Number sequence never reused; gaps may occur on interrupted issue.", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotentAction" } } } } } }, "/billing/invoices/{id}/void": { "post": { "operationId": "post__billing_invoices__id__void", "summary": "Void unpaid invoice; never delete history", "tags": [ "billing" ], "description": "Reverse incorrect receipts first; cannot void while net receipts remain.", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "reason": { "type": "string" } }, "required": [ "idempotencyKey", "expectedVersion", "reason" ], "additionalProperties": true } } } } } }, "/billing/invoices/{id}/payments": { "post": { "operationId": "post__billing_invoices__id__payments", "summary": "Record already-received funds; does not charge customer", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } } } }, "/billing/invoices/{id}/payments/{paymentId}/reverse": { "post": { "operationId": "post__billing_invoices__id__payments__paymentId__reverse", "summary": "Correct receipt ledger; does not refund bank funds", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Unique key per logical write. Retain it when retrying an uncertain result." }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "reversalDate": { "type": "string", "format": "date" }, "reason": { "type": "string" } }, "required": [ "idempotencyKey", "expectedVersion", "reversalDate", "reason" ], "additionalProperties": true } } } } } }, "/billing/invoices/{id}/document": { "get": { "operationId": "get__billing_invoices__id__document", "summary": "Download printable invoice HTML", "tags": [ "billing" ], "description": "Authenticated HTML attachment. Browser Print can save PDF; endpoint does not generate a PDF and does not email anything.", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/billing/costs": { "get": { "operationId": "get__billing_costs", "summary": "List recorded costs", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cost" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__billing_costs", "summary": "Record documented cost", "tags": [ "billing" ], "description": "", "x-required-scopes": [ "billing:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cost" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cost" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cost" } } } } } }, "/billing/summary": { "get": { "operationId": "get__billing_summary", "summary": "Financial period, cash receipts, contribution and aging", "tags": [ "billing" ], "description": "Revenue basis: issued invoices less effective voids, excluding tax. Cash: dated receipts less dated reversals. Costs: manually recorded incurred costs. Contribution is not net profit and does not include unentered expenses, payroll or overhead. Historical receivables reconstruct dated ledger events, not a database point-in-time snapshot.", "x-required-scopes": [ "billing:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FinancialSummary" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "through", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ] } }, "/alerts/outbox": { "get": { "operationId": "get__alerts_outbox", "summary": "Inspect alert candidates and processing state", "tags": [ "alerts" ], "description": "", "x-required-scopes": [ "alerts:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alerts/run": { "post": { "operationId": "post__alerts_run", "summary": "Queue currently due alerts and process Teams delivery", "tags": [ "alerts" ], "description": "Teams only. Three-day yellow, one-day and twelve-hour red. No SMS. Explicit verified destination required; no RLV/UVA default broadcast. Normally omit now. Manual invocation shares deterministic queue IDs and locks with the five-minute timer.", "x-required-scopes": [ "alerts:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "now": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } } } } }, "/alerts/acknowledgements": { "get": { "operationId": "get__alerts_acknowledgements", "summary": "List departure-specific alarm acknowledgements", "tags": [ "alerts" ], "description": "", "x-required-scopes": [ "alerts:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__alerts_acknowledgements", "summary": "Silence this scheduled departure", "tags": [ "alerts" ], "description": "", "x-required-scopes": [ "alerts:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Idempotent replay of an already committed write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }, "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tripId": { "type": "string" }, "reason": { "type": "string", "minLength": 3, "maxLength": 300 }, "scheduledStartAt": { "type": "string", "format": "date-time" } }, "required": [ "tripId", "reason" ], "additionalProperties": true } } } } } }, "/alerts/acknowledgements/{id}": { "patch": { "operationId": "patch__alerts_acknowledgements__id_", "summary": "Withdraw acknowledgement; future due stages may resume", "tags": [ "alerts" ], "description": "", "x-required-scopes": [ "alerts:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "withdrawn" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." } }, "required": [ "status", "expectedVersion" ], "additionalProperties": true } } } } } }, "/notifications/destinations": { "get": { "operationId": "get__notifications_destinations", "summary": "List safe Teams connection metadata", "tags": [ "notifications" ], "description": "", "x-required-scopes": [ "alerts:read", "notifications:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__notifications_destinations", "summary": "Create disabled private Teams connection", "tags": [ "notifications" ], "description": "Initial audience James/Jaliyah @conductordispatch.com. No UVA. Email list is metadata; actual chat membership belongs to Teams Workflow. Save disabled → test → verify actual recipients → confirm and enable.", "x-required-scopes": [ "notifications:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Destination" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } } } }, "/notifications/destinations/{id}": { "patch": { "operationId": "patch__notifications_destinations__id_", "summary": "Edit, disable or verify destination", "tags": [ "notifications" ], "description": "URL/audience/authMode changes require disabled state and a fresh test. Cannot confirm receipt in the same request that changes configuration. Recipient email change requires a replacement connection. No credential returned.", "x-required-scopes": [ "notifications:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Destination" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "audienceEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 25 }, "authMode": { "type": "string", "enum": [ "managed_identity", "secret_url" ], "default": "managed_identity" }, "teamsWorkflowUrl": { "type": "string", "writeOnly": true, "format": "uri", "description": "Private HTTPS Logic Apps/Power Platform Workflow URL. Stored in Key Vault; never returned." }, "enabled": { "type": "boolean", "default": false }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409." }, "confirmedReceipt": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0, "description": "Use the version returned by the latest GET. Stale writes return 409.", "readOnly": true }, "configured": { "type": "boolean", "readOnly": true }, "lastTestAcceptedAt": { "type": "string", "format": "date-time", "readOnly": true }, "confirmedReceiptAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "expectedVersion" ], "additionalProperties": true } } } } } }, "/notifications/destinations/{id}/test": { "post": { "operationId": "post__notifications_destinations__id__test", "summary": "Send generic non-patient connection test", "tags": [ "notifications" ], "description": "HTTP 200 wraps the delivery outcome; inspect data.status. accepted is not proof of human receipt. Failed unchanged-configuration retests preserve historic verified-recipient proof.", "x-required-scopes": [ "notifications:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Delivery" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } } } }, "/notifications/deliveries": { "get": { "operationId": "get__notifications_deliveries", "summary": "List delivery results", "tags": [ "notifications" ], "description": "", "x-required-scopes": [ "alerts:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications/deliveries/{id}/retry": { "post": { "operationId": "post__notifications_deliveries__id__retry", "summary": "Authorize retry with explicit duplicate-risk acknowledgement", "tags": [ "notifications" ], "description": "Accepted delivery cannot be retried. Unknown/sending may already have reached Teams; check actual chat before authorizing retry.", "x-required-scopes": [ "notifications:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Delivery" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledgePossibleDuplicate": { "type": "boolean", "const": true }, "reason": { "type": "string", "minLength": 3 } }, "required": [ "acknowledgePossibleDuplicate", "reason" ], "additionalProperties": true } } } } } }, "/notifications/process": { "post": { "operationId": "post__notifications_process", "summary": "Process existing queued alerts", "tags": [ "notifications" ], "description": "Does not create candidates. At most three alerts per call; current-stage check, request/ack suppression, per-destination dedupe, daily attempt limit and no automatic retry for unknown outcomes.", "x-required-scopes": [ "alerts:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "operationId": "get__webhooks", "summary": "List webhook registration metadata", "tags": [ "webhooks" ], "description": "REGISTRATION ONLY in this pilot. No outbound webhook delivery worker or guaranteed delivery SLA is implemented.", "x-required-scopes": [ "webhooks:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post__webhooks", "summary": "Register future outbound webhook subscription", "tags": [ "webhooks" ], "description": "REGISTRATION ONLY; does not deliver events. Do not depend on this for production integration until outbound signing/delivery is implemented and tested.", "x-required-scopes": [ "webhooks:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "201": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "signingSecret": { "type": "string" } }, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "url", "events" ], "additionalProperties": true } } } } } }, "/connectors/rlv/dry-run": { "post": { "operationId": "post__connectors_rlv_dry_run", "summary": "Map supplied RLV bookings without importing or changing RLV", "tags": [ "connectors" ], "description": "No live RLV access, writes, broker connection, or automatic import. Supply authorized input only.", "x-required-scopes": [ "connectors:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bookings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "maxItems": 1000 } }, "required": [ "bookings" ], "additionalProperties": true } } } } } }, "/exports/trips.csv": { "get": { "operationId": "get__exports_trips_csv", "summary": "Download driver/organization-scoped trip CSV", "tags": [ "exports" ], "description": "", "x-required-scopes": [ "trips:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "through", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ] } }, "/settings/communications": { "get": { "operationId": "get__settings_communications", "summary": "Read central Teams-only communication preferences", "tags": [ "settings" ], "description": "", "x-required-scopes": [ "settings:read", "dispatch:read", "alerts:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommunicationSettings" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patch__settings_communications", "summary": "Update alert channels, template and stages", "tags": [ "settings" ], "description": "SMS cannot be enabled: smsEnabled:true returns 501. Stage IDs and lead times must be unique. Editing rules does not resend already accepted alerts.", "x-required-scopes": [ "notifications:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommunicationSettings" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion" ], "properties": { "teamsEnabled": { "type": "boolean" }, "smsEnabled": { "type": "boolean", "const": false }, "title": { "type": "string", "maxLength": 160 }, "bodyTemplate": { "type": "string", "maxLength": 500, "description": "Generic only. Supported placeholders: {{stage}}, {{start}}, {{reference}}. No patient information." }, "stages": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/CommunicationStage" } }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." } } } } } } } }, "/settings/setup": { "get": { "operationId": "get__settings_setup", "summary": "Read resumable setup and computed readiness checks", "tags": [ "settings" ], "description": "", "x-required-scopes": [ "settings:read", "dispatch:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SetupState" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patch__settings_setup", "summary": "Save setup progress", "tags": [ "settings" ], "description": "Saves reviewed progress only; it does not provision Microsoft accounts, broker connections or compliance approval.", "x-required-scopes": [ "settings:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SetupState" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "step" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." }, "step": { "type": "string", "enum": [ "company", "locations", "fleet", "contracts", "communications", "review" ] }, "reviewedStep": { "type": "string", "enum": [ "company", "locations", "fleet", "contracts", "communications", "review" ] } } } } } } } }, "/settings/setup/complete": { "post": { "operationId": "post__settings_setup_complete", "summary": "Finish configuration review after readiness checks", "tags": [ "settings" ], "description": "Requires company, depot, active fleet/contract and verified Teams destination or explicit Teams-off policy. Missing configuration returns 409. Operational acceptance remains required; completion does not imply broker approval.", "x-required-scopes": [ "settings:write" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SetupState" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expectedVersion", "acknowledgedPilotLimits" ], "properties": { "expectedVersion": { "type": "integer", "minimum": 0, "description": "Use the version from the latest GET. A stale write returns 409." }, "acknowledgedPilotLimits": { "type": "boolean", "const": true } } } } } } } }, "/settings/backups": { "get": { "operationId": "get__settings_backups", "summary": "Read private backup status metadata", "tags": [ "settings" ], "description": "Metadata only. No archive bytes, credentials or download URL are returned. Driver identities are denied.", "x-required-scopes": [ "settings:read", "dispatch:read" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackupStatus" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settings/backups/run": { "post": { "operationId": "post__settings_backups_run", "summary": "Ensure today’s daily logical backup is verified", "tags": [ "settings" ], "description": "Administrator only. Send {}. Exports only the authenticated organization to separate private Azure storage, excludes credentials and attachment file bytes, and verifies readback/integrity. Retries verify the existing daily archive without overwriting it. A same-day snapshot does not include later changes. This is not a transactional point-in-time backup and never restores production data. Capacity limit: 10,000 records / bounded 64 MiB JSON envelope; exceeding the capture limit fails without a partial archive.", "x-required-scopes": [ "*" ], "x-scope-match": "any", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackupProof" }, "requestId": { "type": "string" } }, "required": [ "data", "requestId" ], "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or revoked bearer credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, role, organization or driver boundary denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State/version conflict, duplicate business operation, or infeasible assignment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Address requires review or confirmed coordinates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Application/provider quota or rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error; retain requestId and reconcile before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Required provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Provider/storage operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Backup storage is unconfigured, unavailable or readback could not be verified." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } } }, "x-operation-count": 87, "x-client-timeouts": { "normalSeconds": 45, "dispatchSeconds": 150 }, "x-release-boundaries": [ "Native iPhone/Android apps on hold", "External broker feeds/approvals not implemented by this reference", "Outbound webhook registration only", "Do not import real protected passenger data until operational/privacy acceptance", "Teams requires verified Workflow connection; SMS disabled" ] }