{ "openapi": "3.1.0", "info": { "title": "Fleximotion Ops API", "version": "1.0.0", "description": "Operational source of truth for operators, vehicles, platform accounts, daily activity, alerts, cash, P&L inputs, and transfer-price events." }, "servers": [ { "url": "https://api.fleximotion.example/ops/v1", "description": "Production placeholder" }, { "url": "http://127.0.0.1:4030/ops/v1", "description": "Local development" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Operators" }, { "name": "Vehicles" }, { "name": "Platform Accounts" }, { "name": "Ingestion" }, { "name": "Daily Activity" }, { "name": "Alerts" }, { "name": "Cash" }, { "name": "Performance" }, { "name": "Fuel and Mileage" }, { "name": "Transfer Pricing" }, { "name": "Audit" }, { "name": "Media" }, { "name": "Incidents" }, { "name": "Inspections" }, { "name": "Maintenance" }, { "name": "Expenses" }, { "name": "P&L" }, { "name": "Leaderboard" }, { "name": "Escalations" } ], "paths": { "/operators": { "get": { "tags": [ "Operators" ], "summary": "List operators", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending_activation", "active", "inactive", "suspended" ] } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPage" } } } } } }, "post": { "tags": [ "Operators" ], "summary": "Create operator", "description": "Creates the operational actor linked to Identity person_id. HR may call this through the onboarding handoff.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOperatorRequest" } } } }, "responses": { "201": { "description": "Operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}/activate": { "post": { "tags": [ "Operators" ], "summary": "Activate operator", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Activated operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}": { "get": { "tags": [ "Operators" ], "summary": "Get operator", "parameters": [ { "$ref": "#/components/parameters/OperatorId" } ], "responses": { "200": { "description": "Operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } }, "patch": { "tags": [ "Operators" ], "summary": "Update operational assignment or status", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOperatorRequest" } } } }, "responses": { "200": { "description": "Updated operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}/platform-registrations": { "post": { "tags": [ "Platform Accounts" ], "summary": "Register operator with a platform account", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlatformRegistrationRequest" } } } }, "responses": { "201": { "description": "Registration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformRegistration" } } } } } } }, "/vehicles": { "get": { "tags": [ "Vehicles" ], "summary": "List vehicles", "responses": { "200": { "description": "Vehicles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiclePage" } } } } } }, "post": { "tags": [ "Vehicles" ], "summary": "Create vehicle", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleRequest" } } } }, "responses": { "201": { "description": "Vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } } } } }, "/vehicles/{vehicle_id}": { "patch": { "tags": [ "Vehicles" ], "summary": "Update vehicle assignment, status, or details", "parameters": [ { "name": "vehicle_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } }, "responses": { "200": { "description": "Updated vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } } } } }, "/platform-accounts": { "get": { "tags": [ "Platform Accounts" ], "summary": "List platform accounts", "responses": { "200": { "description": "Platform accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAccountPage" } } } } } }, "post": { "tags": [ "Platform Accounts" ], "summary": "Create platform connector configuration", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlatformAccountRequest" } } } }, "responses": { "201": { "description": "Platform account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAccount" } } } } } } }, "/operators/{operator_id}/daily-activity": { "get": { "tags": [ "Daily Activity" ], "summary": "Get operator daily activity", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Daily records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyActivityPage" } } } } } } }, "/ingestion-runs": { "get": { "tags": [ "Ingestion" ], "summary": "List platform ingestion runs", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Ingestion runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionRunPage" } } } } } }, "post": { "tags": [ "Ingestion" ], "summary": "Ingest normalized daily platform records", "description": "Connector boundary for Bolt, Uber, migration, and manual-correction workers. Each record is resolved through the selected platform account and platform_operator_id. Valid records are upserted independently; rejected records are returned in the run errors array.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIngestionRunRequest" } } } }, "responses": { "201": { "description": "Completed ingestion run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionRun" } } } } } } }, "/daily-performance": { "get": { "tags": [ "Daily Activity" ], "summary": "List canonical daily platform performance", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily platform records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPerformancePage" } } } } } } }, "/team-board": { "get": { "tags": [ "Performance" ], "summary": "Get the risk-sorted live team board", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregated operator operating picture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamBoardResponse" } } } } } } }, "/daily-reports": { "get": { "tags": [ "Daily Activity" ], "summary": "List generated daily report snapshots", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily report snapshots" } } }, "post": { "tags": [ "Daily Activity" ], "summary": "Generate an immutable daily report snapshot", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "record_date" ], "properties": { "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Generated report snapshot" } } } }, "/daily-reports/{report_id}": { "get": { "tags": [ "Daily Activity" ], "summary": "Get a generated daily report snapshot", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily report snapshot" } } } }, "/scheduled-jobs": { "get": { "tags": [ "Audit" ], "summary": "List scheduled job registry health", "responses": { "200": { "description": "Registered jobs with freshness and finality state" } } } }, "/scheduled-job-runs": { "get": { "tags": [ "Audit" ], "summary": "List scheduled job runs", "parameters": [ { "name": "job_name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled job run history" } } } }, "/notification-deliveries": { "get": { "tags": [ "Audit" ], "summary": "List notification outbox delivery attempts", "responses": { "200": { "description": "Notification delivery history for management users" } } } }, "/scheduled-jobs/{job_name}/runs": { "post": { "tags": [ "Audit" ], "summary": "Enqueue a registered scheduled job", "parameters": [ { "name": "job_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requested_window_start": { "type": "string", "format": "date-time" }, "requested_window_end": { "type": "string", "format": "date-time" }, "scheduler_trigger_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Queued job run" } } } }, "/scheduled-job-runs/{run_id}/complete": { "post": { "tags": [ "Audit" ], "summary": "Record completion or failure of a scheduled job run", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] }, "records_received": { "type": "integer" }, "records_upserted": { "type": "integer" }, "records_rejected": { "type": "integer" }, "error_summary": { "type": "string" } } } } } }, "responses": { "200": { "description": "Completed job run" } } } }, "/revenue-pace-profiles": { "get": { "tags": [ "Performance" ], "summary": "List effective-dated revenue pace profiles", "responses": { "200": { "description": "Pace profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenuePaceProfilePage" } } } } } }, "post": { "tags": [ "Performance" ], "summary": "Create a vehicle-class revenue pace profile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRevenuePaceProfileRequest" } } } }, "responses": { "201": { "description": "Pace profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenuePaceProfile" } } } } } } }, "/revenue-pace-profiles/{profile_id}": { "patch": { "tags": [ "Performance" ], "summary": "Update a revenue pace profile", "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRevenuePaceProfileRequest" } } } }, "responses": { "200": { "description": "Updated pace profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenuePaceProfile" } } } } } } }, "/economics-policies": { "get": { "tags": [ "Performance" ], "summary": "List finance economics policies used by analytics dashboards", "responses": { "200": { "description": "Economics policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomicsPolicyPage" } } } } } }, "post": { "tags": [ "Performance" ], "summary": "Create a finance economics policy for labour, overhead and expected-hour assumptions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEconomicsPolicyRequest" } } } }, "responses": { "201": { "description": "Economics policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomicsPolicy" } } } } } } }, "/vehicle-efficiency-policies": { "get": { "tags": [ "Fuel and Mileage" ], "summary": "List fuel and mileage expectation policies", "responses": { "200": { "description": "Efficiency policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleEfficiencyPolicyPage" } } } } } }, "post": { "tags": [ "Fuel and Mileage" ], "summary": "Create a fuel and mileage expectation policy", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleEfficiencyPolicy" } } } }, "responses": { "201": { "description": "Efficiency policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleEfficiencyPolicy" } } } } } } }, "/fuel-issues": { "get": { "tags": [ "Fuel and Mileage" ], "summary": "List supervisor-confirmed fuel issues", "parameters": [ { "name": "operating_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fuel issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelIssuePage" } } } } } }, "post": { "tags": [ "Fuel and Mileage" ], "summary": "Confirm fuel issued to an operator and vehicle", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFuelIssueRequest" } } } }, "responses": { "201": { "description": "Fuel issue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelIssue" } } } } } } }, "/mileage-reconciliations": { "get": { "tags": [ "Fuel and Mileage" ], "summary": "Calculate daily fuel-efficiency and tracker mileage exceptions", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Mileage reconciliations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MileageReconciliationPage" } } } } } } }, "/alerts": { "get": { "tags": [ "Alerts" ], "summary": "List alerts", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "resolution_status", "in": "query", "schema": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "snoozed", "escalated" ] } } ], "responses": { "200": { "description": "Alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPage" } } } } } } }, "/alerts/{alert_id}/acknowledge": { "post": { "tags": [ "Alerts" ], "summary": "Acknowledge alert", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeAlertRequest" } } } }, "responses": { "200": { "description": "Alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/alerts/{alert_id}/resolve": { "post": { "tags": [ "Alerts" ], "summary": "Resolve alert", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveAlertRequest" } } } }, "responses": { "200": { "description": "Alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/cash/status": { "get": { "tags": [ "Cash" ], "summary": "Get expected versus remitted cash status", "description": "Finance and manager-facing closeout view. Expected cash is currently derived from platform cash-trip share until exact cash receipts are available from connectors.", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scoped cash status rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashStatusPage" } } } } } } }, "/cash/adjustments": { "get": { "tags": [ "Cash" ], "summary": "List finance cash adjustments and evidence references", "parameters": [ { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "adjustment_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Scoped cash adjustments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashAdjustmentPage" } } } } } }, "post": { "tags": [ "Cash" ], "summary": "Record a finance cash adjustment or reversal", "description": "Requires service, owner/admin, or an active scoped Finance assignment. Manager-scoped users can review cash status and adjustment history but cannot create adjustments. The API rejects adjustments for accounting periods already closed by Payments.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCashAdjustmentRequest" } } } }, "responses": { "201": { "description": "Cash adjustment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashAdjustment" } } } }, "403": { "description": "Missing Finance authority, or the selected accounting period is locked." } } } }, "/daily-closeouts": { "get": { "tags": [ "Closeouts" ], "summary": "List submitted daily closeouts", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scoped closeouts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCloseoutPage" } } } } } }, "post": { "tags": [ "Closeouts" ], "summary": "Submit or update a supervisor daily closeout", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDailyCloseoutRequest" } } } }, "responses": { "201": { "description": "Daily closeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCloseout" } } } } } } }, "/cash/transactions": { "get": { "tags": [ "Cash" ], "summary": "List Monnify-derived cash transactions", "parameters": [ { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Scoped cash transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashTransactionPage" } } } } } }, "post": { "tags": [ "Cash" ], "summary": "Accept a verified Monnify cash transaction", "description": "Internal service endpoint called by the Payments Integration service after provider verification and account matching.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCashTransactionRequest" } } } }, "responses": { "201": { "description": "Cash transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashTransaction" } } } } } } }, "/operators/{operator_id}/monnify-account": { "patch": { "tags": [ "Cash" ], "summary": "Attach a provisioned Monnify account to an operator", "description": "Internal service endpoint called by the Payments Integration service after reserved-account provisioning.", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "monnify_account_number" ], "properties": { "monnify_account_number": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}/cash": { "get": { "tags": [ "Cash" ], "summary": "Get an operator cash position", "parameters": [ { "$ref": "#/components/parameters/OperatorId" } ], "responses": { "200": { "description": "Operator cash position" } } } }, "/amoebas/{amoeba_id}/performance": { "get": { "tags": [ "Performance" ], "summary": "Get amoeba performance", "description": "Canonical operational performance snapshot for TMS and management dashboards.", "parameters": [ { "$ref": "#/components/parameters/AmoebaId" }, { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter" ] } }, { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Performance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmoebaPerformance" } } } } } } }, "/transfer-price-events": { "post": { "tags": [ "Transfer Pricing" ], "summary": "Accept transfer-price event from TMS", "description": "Records TMS-created transfer-price events as Ops P&L inputs. This endpoint is idempotent and service-token only.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferPriceEventRequest" } } } }, "responses": { "202": { "description": "Accepted transfer-price event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPriceEvent" } } } } } }, "get": { "tags": [ "Transfer Pricing" ], "summary": "List transfer-price events", "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPriceEventPage" } } } } } } }, "/audit": { "get": { "tags": [ "Audit" ], "summary": "List append-only Ops audit entries", "responses": { "200": { "description": "Audit entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEntryPage" } } } } } } }, "/media": { "post": { "tags": [ "Media" ], "summary": "Register a camera capture", "description": "Uploads a base64-encoded camera capture with GPS coordinates and capture timestamp. Capture-time drift beyond the configured tolerance is rejected when MEDIA_STRICT_CAPTURE is enabled.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMediaRequest" } } } }, "responses": { "201": { "description": "Stored media metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaFile" } } } } } } }, "/media/{media_id}": { "get": { "tags": [ "Media" ], "summary": "Get media metadata", "parameters": [ { "$ref": "#/components/parameters/MediaId" } ], "responses": { "200": { "description": "Media metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaFile" } } } } } } }, "/media/{media_id}/content": { "get": { "tags": [ "Media" ], "summary": "Download media content", "parameters": [ { "$ref": "#/components/parameters/MediaId" } ], "responses": { "200": { "description": "Binary media content in the stored content type" } } } }, "/deviation-reason-codes": { "get": { "tags": [ "Alerts" ], "summary": "List standardised deviation reason codes", "responses": { "200": { "description": "Array of reason codes" } } } }, "/alerts/{alert_id}/deviation-reason": { "post": { "tags": [ "Alerts" ], "summary": "Submit an operator deviation reason for an alert", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitDeviationReasonRequest" } } } }, "responses": { "200": { "description": "Alert with pending deviation review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/alerts/{alert_id}/deviation-reason/review": { "post": { "tags": [ "Alerts" ], "summary": "Accept or reject an operator deviation reason", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDeviationReasonRequest" } } } }, "responses": { "200": { "description": "Alert with reviewed deviation reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/alerts/{alert_id}/escalate": { "post": { "tags": [ "Alerts" ], "summary": "Escalate an alert to the manager escalation queue", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalateAlertRequest" } } } }, "responses": { "200": { "description": "Escalated alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/incidents": { "get": { "tags": [ "Incidents" ], "summary": "List incidents in scope", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "acknowledged", "resolved" ] } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "incident_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Incident collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentCollection" } } } } } }, "post": { "tags": [ "Incidents" ], "summary": "Report a field incident", "description": "Accident and police incidents are high severity and enter the manager escalation queue if unacknowledged past the configured window.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIncidentRequest" } } } }, "responses": { "201": { "description": "Created incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/incidents/{incident_id}/acknowledge": { "post": { "tags": [ "Incidents" ], "summary": "Acknowledge an incident", "parameters": [ { "$ref": "#/components/parameters/IncidentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Acknowledged incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/incidents/{incident_id}/resolve": { "post": { "tags": [ "Incidents" ], "summary": "Resolve an incident with notes", "parameters": [ { "$ref": "#/components/parameters/IncidentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIncidentRequest" } } } }, "responses": { "200": { "description": "Resolved incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/inspections": { "get": { "tags": [ "Inspections" ], "summary": "List vehicle inspections in scope", "parameters": [ { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } }, { "name": "review_status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inspection collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionCollection" } } } } } }, "post": { "tags": [ "Inspections" ], "summary": "Submit a supervisor vehicle inspection", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInspectionRequest" } } } }, "responses": { "201": { "description": "Created inspection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspection" } } } } } } }, "/inspections/compliance": { "get": { "tags": [ "Inspections" ], "summary": "48-hour inspection compliance summary", "responses": { "200": { "description": "Compliance summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionCompliance" } } } } } } }, "/inspections/{inspection_id}/review": { "post": { "tags": [ "Inspections" ], "summary": "Approve an inspection or request follow-up", "parameters": [ { "$ref": "#/components/parameters/InspectionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInspectionRequest" } } } }, "responses": { "200": { "description": "Reviewed inspection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspection" } } } } } } }, "/maintenance-reports": { "get": { "tags": [ "Maintenance" ], "summary": "List maintenance reports in scope", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "in_repair", "resolved" ] } }, { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Maintenance report collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceReportCollection" } } } } } }, "post": { "tags": [ "Maintenance" ], "summary": "Report a vehicle maintenance issue", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMaintenanceReportRequest" } } } }, "responses": { "201": { "description": "Created maintenance report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceReport" } } } } } } }, "/maintenance-reports/{maintenance_id}/status": { "post": { "tags": [ "Maintenance" ], "summary": "Move a maintenance report between open, in_repair and resolved", "description": "Resolved reports may carry a cost_ngn which feeds the amoeba P&L as a variable maintenance cost.", "parameters": [ { "$ref": "#/components/parameters/MaintenanceId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMaintenanceStatusRequest" } } } }, "responses": { "200": { "description": "Updated maintenance report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceReport" } } } } } } }, "/expenses": { "get": { "tags": [ "Expenses" ], "summary": "List expenses for a period", "parameters": [ { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Expense collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpenseCollection" } } } } } }, "post": { "tags": [ "Expenses" ], "summary": "Record a direct amoeba expense or a central cost", "description": "Central expenses (allocation=central, no amoeba_id) are allocated across amoebas by active-operator headcount in the P&L view.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExpenseRequest" } } } }, "responses": { "201": { "description": "Created expense", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Expense" } } } } } } }, "/pnl": { "get": { "tags": [ "P&L" ], "summary": "Amoeba P&L for a period", "description": "Net Earnings minus direct expenses, resolved maintenance costs and headcount-allocated central costs, adjusted by transfer-price credits and charges.", "parameters": [ { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "P&L summary and per-amoeba rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfitAndLoss" } } } } } } }, "/leaderboard": { "get": { "tags": [ "Leaderboard" ], "summary": "Sortable operator leaderboard with weighted Performance Score", "description": "Performance Score combines acceptance, time online, cash receipt and revenue components using admin-configured weights. Operator-role callers receive the revenue component as null.", "parameters": [ { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "score", "net_earnings", "acceptance", "trips", "online", "cash" ] } } ], "responses": { "200": { "description": "Ranked leaderboard entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leaderboard" } } } } } } }, "/leaderboard-config": { "get": { "tags": [ "Leaderboard" ], "summary": "Get leaderboard weights and visibility", "responses": { "200": { "description": "Leaderboard configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardConfig" } } } } } }, "post": { "tags": [ "Leaderboard" ], "summary": "Update leaderboard weights and visibility", "description": "Weights must sum to 1.0.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardConfig" } } } }, "responses": { "200": { "description": "Updated configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardConfig" } } } } } } }, "/escalations": { "get": { "tags": [ "Escalations" ], "summary": "Manager escalation queue", "description": "Escalated or tier-2+ alerts, unacknowledged high-severity incidents, overdue vehicle inspections, missing daily closeouts and open maintenance reports for the caller's scope.", "responses": { "200": { "description": "Escalation queue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationQueue" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT or service token" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 160 } }, "OperatorId": { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^operator_" } }, "AlertId": { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^alert_" } }, "AmoebaId": { "name": "amoeba_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^amoeba_" } }, "MediaId": { "name": "media_id", "in": "path", "required": true, "description": "Media file identifier", "schema": { "type": "string" } }, "IncidentId": { "name": "incident_id", "in": "path", "required": true, "description": "Incident identifier", "schema": { "type": "string" } }, "InspectionId": { "name": "inspection_id", "in": "path", "required": true, "description": "Inspection identifier", "schema": { "type": "string" } }, "MaintenanceId": { "name": "maintenance_id", "in": "path", "required": true, "description": "Maintenance report identifier", "schema": { "type": "string" } } }, "schemas": { "Operator": { "type": "object", "required": [ "operator_id", "person_id", "operator_status", "amoeba_id" ], "properties": { "operator_id": { "type": "string" }, "person_id": { "type": "string" }, "operator_type": { "type": "string", "enum": [ "driver", "rider", "courier" ] }, "operator_status": { "type": "string", "enum": [ "pending_activation", "active", "inactive", "suspended" ] }, "amoeba_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ] }, "supervisor_person_id": { "type": [ "string", "null" ] }, "vehicle_id": { "type": [ "string", "null" ] }, "daily_revenue_target_ngn": { "type": [ "number", "null" ] } } }, "CreateOperatorRequest": { "type": "object", "required": [ "person_id", "operator_type", "amoeba_id", "site_id" ], "properties": { "person_id": { "type": "string" }, "operator_type": { "type": "string", "enum": [ "driver", "rider", "courier" ] }, "amoeba_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ] }, "supervisor_person_id": { "type": [ "string", "null" ] }, "daily_revenue_target_ngn": { "type": [ "number", "null" ] }, "legacy_source": { "type": "object" } } }, "UpdateOperatorRequest": { "type": "object", "properties": { "operator_type": { "type": "string", "enum": [ "driver", "rider", "courier" ] }, "operator_status": { "type": "string", "enum": [ "pending_activation", "active", "inactive", "suspended" ] }, "amoeba_id": { "type": "string" }, "site_id": { "type": "string" }, "supervisor_person_id": { "type": [ "string", "null" ] }, "vehicle_id": { "type": [ "string", "null" ] }, "daily_revenue_target_ngn": { "type": [ "number", "null" ] } } }, "OperatorPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } } } }, "Vehicle": { "type": "object", "required": [ "vehicle_id", "plate", "vehicle_type", "status" ], "properties": { "vehicle_id": { "type": "string" }, "plate": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "van" ] }, "amoeba_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "in_repair" ] } } }, "CreateVehicleRequest": { "type": "object", "required": [ "plate", "vehicle_type", "amoeba_id" ], "properties": { "plate": { "type": "string" }, "vehicle_type": { "type": "string" }, "amoeba_id": { "type": "string" } } }, "VehiclePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } } } }, "PlatformAccount": { "type": "object", "required": [ "platform_account_id", "platform", "display_name", "vehicle_type", "account_subtype", "credentials_key", "is_active" ], "properties": { "platform_account_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "bolt", "uber", "indrive", "other" ] }, "display_name": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "any" ] }, "account_subtype": { "type": "string", "enum": [ "ride_hailing", "courier", "general" ] }, "credentials_key": { "type": "string", "description": "Environment/secrets prefix only; credentials are never returned." }, "external_account_id": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } } }, "CreatePlatformAccountRequest": { "type": "object", "required": [ "platform", "display_name", "vehicle_type", "account_subtype", "credentials_key" ], "properties": { "platform": { "type": "string", "enum": [ "bolt", "uber", "indrive", "other" ] }, "display_name": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "any" ] }, "account_subtype": { "type": "string", "enum": [ "ride_hailing", "courier", "general" ] }, "credentials_key": { "type": "string" }, "external_account_id": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean", "default": true } } }, "PlatformRegistration": { "type": "object", "required": [ "registration_id", "operator_id", "platform_account_id", "platform_operator_id", "registration_status" ], "properties": { "registration_id": { "type": "string" }, "operator_id": { "type": "string" }, "platform_account_id": { "type": "string" }, "platform_operator_id": { "type": "string" }, "registration_status": { "type": "string", "enum": [ "registered", "active", "inactive", "suspended" ] } } }, "CreatePlatformRegistrationRequest": { "type": "object", "required": [ "platform_account_id", "platform_operator_id" ], "properties": { "platform_account_id": { "type": "string" }, "platform_operator_id": { "type": "string" }, "registration_status": { "type": "string", "enum": [ "registered", "active", "inactive", "suspended" ] } } }, "PlatformAccountPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformAccount" } } } }, "NormalizedDailyRecordInput": { "type": "object", "required": [ "platform_operator_id", "trips_total", "trips_completed", "ride_revenue_ngn", "hours_online" ], "properties": { "platform_operator_id": { "type": "string" }, "trips_total": { "type": "integer", "minimum": 0 }, "trips_completed": { "type": "integer", "minimum": 0 }, "trips_cancelled": { "type": "integer", "minimum": 0 }, "trips_no_response": { "type": "integer", "minimum": 0 }, "trips_rejected": { "type": "integer", "minimum": 0 }, "ride_revenue_ngn": { "type": "number", "minimum": 0 }, "net_earnings_ngn": { "type": "number", "minimum": 0 }, "booking_fees_ngn": { "type": "number", "minimum": 0 }, "cash_trips": { "type": "integer", "minimum": 0 }, "card_trips": { "type": "integer", "minimum": 0 }, "acceptance_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "cancellation_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "completion_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "hours_online": { "type": "number", "minimum": 0 }, "official_distance_km": { "type": [ "number", "null" ], "minimum": 0 }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_status": { "type": "string", "enum": [ "online", "offline", "not_seen_today", "checked_out", "unknown" ] }, "data_quality": { "type": "string", "enum": [ "authoritative", "derived", "heuristic", "degraded" ] }, "provenance": { "type": "object" }, "raw_payload": { "type": "object" } } }, "CreateIngestionRunRequest": { "type": "object", "required": [ "platform_account_id", "record_date", "records" ], "properties": { "platform_account_id": { "type": "string" }, "record_date": { "type": "string", "format": "date", "description": "Africa/Lagos business date." }, "source": { "type": "string", "enum": [ "live", "migration", "manual_correction", "connector_test" ], "default": "live" }, "records": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/NormalizedDailyRecordInput" } } } }, "IngestionRun": { "type": "object", "properties": { "ingestion_run_id": { "type": "string" }, "platform_account_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "source": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "completed_with_errors", "failed" ] }, "records_received": { "type": "integer" }, "records_upserted": { "type": "integer" }, "records_rejected": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } } } }, "IngestionRunPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionRun" } } } }, "DailyPerformancePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "TeamBoardResponse": { "type": "object", "required": [ "record_date", "data" ], "properties": { "record_date": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object" } } } }, "RevenueCheckpoint": { "type": "object", "required": [ "time", "expected_pct" ], "properties": { "time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" }, "expected_pct": { "type": "number", "minimum": 0, "maximum": 100 } } }, "RevenuePaceProfile": { "type": "object", "required": [ "pace_profile_id", "vehicle_type", "daily_target_ngn", "checkpoints" ], "properties": { "pace_profile_id": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "other" ] }, "day_type": { "type": "string" }, "daily_target_ngn": { "type": "number" }, "checkpoints": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueCheckpoint" } }, "warning_tolerance_pct": { "type": "number" }, "critical_tolerance_pct": { "type": "number" }, "effective_from": { "type": "string", "format": "date" }, "effective_to": { "type": [ "string", "null" ], "format": "date" } } }, "CreateRevenuePaceProfileRequest": { "allOf": [ { "$ref": "#/components/schemas/RevenuePaceProfile" } ], "description": "pace_profile_id is generated by the service." }, "RevenuePaceProfilePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenuePaceProfile" } } } }, "EconomicsPolicy": { "type": "object", "required": [ "policy_name", "admin_staff_daily_cost_ngn", "operator_labour_share_pct", "daily_overhead_ngn", "expected_hours_per_operator", "effective_from" ], "properties": { "economics_policy_id": { "type": "string" }, "policy_name": { "type": "string" }, "admin_staff_daily_cost_ngn": { "type": "number" }, "operator_labour_share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "daily_overhead_ngn": { "type": "number" }, "expected_hours_per_operator": { "type": "number" }, "effective_from": { "type": "string", "format": "date" }, "effective_to": { "type": [ "string", "null" ], "format": "date" } } }, "CreateEconomicsPolicyRequest": { "allOf": [ { "$ref": "#/components/schemas/EconomicsPolicy" } ], "description": "economics_policy_id is generated by the service." }, "EconomicsPolicyPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EconomicsPolicy" } } } }, "VehicleEfficiencyPolicy": { "type": "object", "required": [ "vehicle_type", "standard_daily_fuel_quantity", "fuel_unit", "expected_distance_km" ], "properties": { "efficiency_policy_id": { "type": "string" }, "vehicle_type": { "type": "string" }, "make_model": { "type": [ "string", "null" ] }, "fuel_type": { "type": "string" }, "standard_daily_fuel_quantity": { "type": "number" }, "fuel_unit": { "type": "string" }, "expected_distance_km": { "type": "number" }, "allowed_variance_pct": { "type": "number", "default": 10 }, "effective_from": { "type": "string", "format": "date" } } }, "VehicleEfficiencyPolicyPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleEfficiencyPolicy" } } } }, "FuelIssue": { "type": "object", "required": [ "fuel_issue_id", "operator_id", "vehicle_id", "operating_date", "quantity", "unit" ], "properties": { "fuel_issue_id": { "type": "string" }, "operator_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "operating_date": { "type": "string", "format": "date" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "notes": { "type": [ "string", "null" ] } } }, "CreateFuelIssueRequest": { "type": "object", "required": [ "operator_id", "vehicle_id", "operating_date", "quantity", "unit" ], "properties": { "operator_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "operating_date": { "type": "string", "format": "date" }, "quantity": { "type": "number", "minimum": 0 }, "unit": { "type": "string" }, "notes": { "type": [ "string", "null" ] } } }, "FuelIssuePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelIssue" } } } }, "MileageReconciliationPage": { "type": "object", "required": [ "record_date", "data" ], "properties": { "record_date": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object", "properties": { "official_distance_status": { "type": "string", "enum": [ "acceptable", "exception", "not_available" ] }, "tracker_variance_status": { "type": "string", "enum": [ "acceptable", "exception", "tracker_unavailable", "no_tracker_data" ] } } } } } }, "DailyActivityPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "Alert": { "type": "object", "required": [ "alert_id", "operator_id", "alert_type", "resolution_status" ], "properties": { "alert_id": { "type": "string" }, "operator_id": { "type": "string" }, "platform": { "type": "string" }, "alert_type": { "type": "string" }, "alert_date": { "type": "string", "format": "date" }, "tier": { "type": "integer" }, "resolution_status": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "snoozed", "escalated" ] }, "metadata": { "type": "object" } } }, "AlertPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } } } }, "AcknowledgeAlertRequest": { "type": "object", "properties": { "note": { "type": "string" } } }, "ResolveAlertRequest": { "type": "object", "required": [ "resolution_notes" ], "properties": { "resolution_notes": { "type": "string" } } }, "CreateCashTransactionRequest": { "type": "object", "required": [ "operator_id", "amount_ngn", "transaction_ref", "paid_at", "monnify_account_number" ], "properties": { "operator_id": { "type": "string" }, "amount_ngn": { "type": "number", "exclusiveMinimum": 0 }, "transaction_ref": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time" }, "monnify_account_number": { "type": "string" }, "reconciliation_status": { "type": "string" }, "provider_payload": { "type": [ "object", "null" ] } } }, "CashTransaction": { "type": "object", "properties": { "cash_transaction_id": { "type": "string" }, "operator_id": { "type": "string" }, "amount_ngn": { "type": "number" }, "transaction_ref": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time" }, "monnify_account_number": { "type": "string" }, "reconciliation_status": { "type": "string" } } }, "CashTransactionPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashTransaction" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CashStatus": { "type": "object", "properties": { "operator_id": { "type": "string" }, "person_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" }, "expected_cash_ngn": { "type": "number" }, "remitted_cash_ngn": { "type": "number" }, "adjustment_ngn": { "type": "number" }, "net_position_ngn": { "type": "number" }, "cash_status": { "type": "string", "enum": [ "balanced", "shortfall", "in_credit", "no_expected_cash" ] }, "expected_cash_basis": { "type": "string" }, "transaction_count": { "type": "integer" }, "latest_paid_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CashStatusPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashStatus" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CreateCashAdjustmentRequest": { "type": "object", "required": [ "operator_id", "adjustment_date", "amount_ngn", "adjustment_type", "reason" ], "properties": { "operator_id": { "type": "string" }, "adjustment_date": { "type": "string", "format": "date" }, "amount_ngn": { "type": "number" }, "adjustment_type": { "type": "string", "enum": [ "credit", "debit", "reversal" ] }, "reason": { "type": "string" }, "related_transaction_ref": { "type": [ "string", "null" ] }, "evidence_reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } } }, "CashAdjustment": { "type": "object", "properties": { "cash_adjustment_id": { "type": "string" }, "operator_id": { "type": "string" }, "adjustment_date": { "type": "string", "format": "date" }, "amount_ngn": { "type": "number" }, "adjustment_type": { "type": "string" }, "reason": { "type": "string" }, "related_transaction_ref": { "type": [ "string", "null" ] }, "evidence_reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_by_person_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "CashAdjustmentPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashAdjustment" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CreateDailyCloseoutRequest": { "type": "object", "required": [ "record_date", "amoeba_id" ], "properties": { "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" }, "supervisor_person_id": { "type": "string" }, "status": { "type": "string" }, "unresolved_alert_count": { "type": "integer", "minimum": 0 }, "notes": { "type": [ "string", "null" ] } } }, "DailyCloseout": { "type": "object", "properties": { "closeout_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" }, "supervisor_person_id": { "type": "string" }, "status": { "type": "string" }, "unresolved_alert_count": { "type": "integer" }, "cash_summary": { "type": "object" }, "notes": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string", "format": "date-time" } } }, "DailyCloseoutPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyCloseout" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "AmoebaPerformance": { "type": "object", "properties": { "amoeba_id": { "type": "string" }, "window": { "type": "string" }, "period_start": { "type": "string", "format": "date" }, "revenue_ngn": { "type": "number" }, "utilisation_pct": { "type": "number" }, "he_ngn_per_hour": { "type": "number" }, "active_operator_count": { "type": "integer" } } }, "CreateTransferPriceEventRequest": { "type": "object", "required": [ "transfer_price_event_id", "date", "provider_amoeba_id", "consumer_amoeba_id", "amount_ngn" ], "properties": { "transfer_price_event_id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "provider_amoeba_id": { "type": "string" }, "consumer_amoeba_id": { "type": "string" }, "amount_ngn": { "type": "number" }, "source_tms_url": { "type": "string" } } }, "TransferPriceEvent": { "type": "object", "properties": { "transfer_price_event_id": { "type": "string" }, "ops_record_id": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "posted_to_pnl" ] } } }, "TransferPriceEventPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransferPriceEvent" } } } }, "AuditEntryPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "CreateMediaRequest": { "type": "object", "required": [ "content_type", "content_base64", "captured_at" ], "properties": { "kind": { "type": "string", "description": "What the capture evidences, e.g. incident_evidence, inspection_photo, vehicle_return" }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "video/mp4" ] }, "content_base64": { "type": "string", "description": "Base64-encoded bytes, max 3MB decoded" }, "captured_at": { "type": "string", "format": "date-time" }, "gps_lat": { "type": [ "number", "null" ] }, "gps_lng": { "type": [ "number", "null" ] } } }, "MediaFile": { "type": "object", "properties": { "media_id": { "type": "string" }, "kind": { "type": "string" }, "content_type": { "type": "string" }, "byte_size": { "type": "integer" }, "sha256": { "type": "string" }, "captured_at": { "type": "string", "format": "date-time" }, "gps_lat": { "type": [ "number", "null" ] }, "gps_lng": { "type": [ "number", "null" ] }, "uploaded_by_person_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SubmitDeviationReasonRequest": { "type": "object", "required": [ "reason_code" ], "properties": { "reason_code": { "type": "string", "enum": [ "network_app_issue", "vehicle_fault", "fuel_charging_problem", "platform_account_blocked", "personal_emergency", "other" ] }, "note": { "type": "string", "maxLength": 140, "description": "Required when reason_code is 'other'" } } }, "ReviewDeviationReasonRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accepted", "rejected" ] }, "note": { "type": "string" } } }, "EscalateAlertRequest": { "type": "object", "properties": { "note": { "type": "string" } } }, "CreateIncidentRequest": { "type": "object", "required": [ "operator_id", "incident_type" ], "properties": { "operator_id": { "type": "string" }, "vehicle_id": { "type": [ "string", "null" ] }, "incident_type": { "type": "string", "enum": [ "accident", "breakdown", "police", "fuel_funds", "low_battery", "other" ] }, "description": { "type": "string", "maxLength": 500 }, "gps_lat": { "type": [ "number", "null" ] }, "gps_lng": { "type": [ "number", "null" ] }, "media_ids": { "type": "array", "items": { "type": "string" } }, "occurred_at": { "type": "string", "format": "date-time" } } }, "Incident": { "type": "object", "properties": { "incident_id": { "type": "string" }, "operator_id": { "type": "string" }, "vehicle_id": { "type": [ "string", "null" ] }, "incident_type": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "normal" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "acknowledged", "resolved" ] }, "media_ids": { "type": "array", "items": { "type": "string" } }, "occurred_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolution_notes": { "type": [ "string", "null" ] } } }, "IncidentCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ResolveIncidentRequest": { "type": "object", "required": [ "resolution_notes" ], "properties": { "resolution_notes": { "type": "string" } } }, "CreateInspectionRequest": { "type": "object", "required": [ "vehicle_id", "condition" ], "properties": { "vehicle_id": { "type": "string" }, "odometer_km": { "type": [ "number", "null" ] }, "fuel_level_pct": { "type": [ "number", "null" ] }, "condition": { "type": "string", "enum": [ "ok", "minor_issues", "needs_repair" ] }, "issue_categories": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "maxLength": 500 }, "media_ids": { "type": "array", "items": { "type": "string" } } } }, "Inspection": { "type": "object", "properties": { "inspection_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "amoeba_id": { "type": "string" }, "inspected_by_person_id": { "type": "string" }, "odometer_km": { "type": [ "number", "null" ] }, "fuel_level_pct": { "type": [ "number", "null" ] }, "condition": { "type": "string" }, "issue_categories": { "type": "array", "items": { "type": "string" } }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "approved", "follow_up" ] }, "inspected_at": { "type": "string", "format": "date-time" } } }, "InspectionCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inspection" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ReviewInspectionRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "follow_up" ] }, "note": { "type": "string" } } }, "InspectionCompliance": { "type": "object", "properties": { "total_active_vehicles": { "type": "integer" }, "current": { "type": "integer" }, "overdue": { "type": "integer" }, "compliance_pct": { "type": [ "number", "null" ] }, "vehicles": { "type": "array", "items": { "type": "object" } } } }, "CreateMaintenanceReportRequest": { "type": "object", "required": [ "vehicle_id", "category" ], "properties": { "vehicle_id": { "type": "string" }, "operator_id": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "tyres", "brakes", "engine", "electrical", "body_damage", "other" ] }, "description": { "type": "string", "maxLength": 200 }, "media_ids": { "type": "array", "items": { "type": "string" } } } }, "MaintenanceReport": { "type": "object", "properties": { "maintenance_id": { "type": "string" }, "operator_id": { "type": [ "string", "null" ] }, "vehicle_id": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_repair", "resolved" ] }, "cost_ngn": { "type": [ "number", "string", "null" ] }, "resolution_notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "MaintenanceReportCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MaintenanceReport" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "UpdateMaintenanceStatusRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "in_repair", "resolved" ] }, "cost_ngn": { "type": [ "number", "null" ] }, "resolution_notes": { "type": "string" } } }, "CreateExpenseRequest": { "type": "object", "required": [ "expense_date", "category", "amount_ngn" ], "properties": { "expense_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": [ "string", "null" ], "description": "Required for direct expenses; omit for central costs" }, "category": { "type": "string", "enum": [ "fuel", "maintenance", "rent", "salaries", "utilities", "overhead", "other" ] }, "description": { "type": "string", "maxLength": 300 }, "amount_ngn": { "type": "number" }, "allocation": { "type": "string", "enum": [ "direct", "central" ] }, "evidence_reference": { "type": [ "string", "null" ] } } }, "Expense": { "type": "object", "properties": { "expense_id": { "type": "string" }, "expense_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "amount_ngn": { "type": [ "number", "string" ] }, "allocation": { "type": "string" }, "evidence_reference": { "type": [ "string", "null" ] } } }, "ExpenseCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Expense" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ProfitAndLoss": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "central_expenses_ngn": { "type": "number" }, "allocation_basis": { "type": "string" }, "totals": { "type": "object" }, "amoebas": { "type": "array", "items": { "type": "object", "properties": { "amoeba_id": { "type": "string" }, "net_earnings_ngn": { "type": "number" }, "direct_expenses_ngn": { "type": "number" }, "maintenance_costs_ngn": { "type": "number" }, "central_allocation_ngn": { "type": "number" }, "transfer_price_credits_ngn": { "type": "number" }, "transfer_price_charges_ngn": { "type": "number" }, "gross_pnl_ngn": { "type": "number" }, "hourly_pnl_ngn": { "type": [ "number", "null" ] }, "target_attainment_pct": { "type": [ "number", "null" ] } } } } } }, "Leaderboard": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "sort": { "type": "string" }, "weights": { "type": "object" }, "company_wide_visible": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "badge": { "type": [ "string", "null" ], "enum": [ "gold", "silver", "bronze", null ] }, "operator_id": { "type": "string" }, "performance_score": { "type": "number" }, "components": { "type": "object" } } } } } }, "LeaderboardConfig": { "type": "object", "properties": { "acceptance_weight": { "type": [ "number", "string" ] }, "online_weight": { "type": [ "number", "string" ] }, "cash_weight": { "type": [ "number", "string" ] }, "revenue_weight": { "type": [ "number", "string" ] }, "default_timeline": { "type": "string" }, "company_wide_visible": { "type": "boolean" } } }, "EscalationQueue": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time" }, "escalated_alerts": { "type": "array", "items": { "type": "object" } }, "high_severity_incidents_unacknowledged": { "type": "array", "items": { "type": "object" } }, "open_incidents": { "type": "array", "items": { "type": "object" } }, "overdue_inspections": { "type": "array", "items": { "type": "object" } }, "missing_closeouts_today": { "type": "array", "items": { "type": "object" } }, "open_maintenance_reports": { "type": "array", "items": { "type": "object" } }, "counts": { "type": "object" } } } } } }