{
  "openapi": "3.1.0",
  "info": {
    "title": "Fleetkeep API",
    "version": "0.8.0",
    "summary": "UK fleet compliance, equipment and maintenance API",
    "description": "Read and write end-user vehicle, equipment lifecycle, maintenance-task and defect records on Fleetkeep. Authorisation is OAuth 2.1 with PKCE; the resource owner is a Fleetkeep end user who has granted a partner client access to their fleet. All dates are ISO 8601 calendar dates (YYYY-MM-DD). All endpoints require a Bearer access token. Consequential maintenance and defect actions require a short-lived, version-bound confirmation token. Per-token rate limit: 60 requests per minute. See /.well-known/oauth-authorization-server for OAuth metadata and /.well-known/oauth-protected-resource for the resource server descriptor.",
    "contact": {
      "name": "Fleetkeep partner integration",
      "url": "https://fleetkeep.co.uk/contact",
      "email": "hello@fleetkeep.co.uk"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://fleetkeep.co.uk/legal/terms"
    }
  },
  "servers": [
    {
      "url": "https://fleetkeep.co.uk",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Vehicles",
      "description": "Manage the authorised user's vehicles."
    },
    {
      "name": "Imports",
      "description": "Preview and explicitly confirm fleet spreadsheet imports."
    },
    {
      "name": "Equipment",
      "description": "Manage installed equipment, accounts and preserved lifecycle history."
    },
    {
      "name": "Maintenance",
      "description": "Manage maintenance tasks while preserving completed history."
    },
    {
      "name": "Defects",
      "description": "Report and complete defects while preserving defect history."
    },
    {
      "name": "Reminders",
      "description": "Manage consented reminder settings and contacts. External verification is previewed and confirmed separately."
    },
    {
      "name": "Bookings",
      "description": "Save maintenance-derived booking requests. Garage email is a separate confirmed action."
    },
    {
      "name": "Tracking",
      "description": "Read stored fleet tracking snapshots and authorised Wex route data without changing provider connections."
    },
    {
      "name": "Account",
      "description": "Read the authorised user's Fleetkeep profile and approved driver guidance."
    },
    {
      "name": "Exports",
      "description": "Download private no-store account and fleet spreadsheet exports."
    }
  ],
  "security": [
    {
      "oauth2": ["vehicles:read"]
    }
  ],
  "paths": {
    "/api/v1/jobs/import": {
      "post": {
        "operationId": "importProviderJobs",
        "summary": "Preview or apply a caller-authorised ServiceM8 or Simpro job import.",
        "description": "Use the owner's saved connection with useSavedConnection=true, or supply a current provider accessToken for this request only. Set up saved connections at /dashboard/jobs/connections. Reads up to 5,000 jobs over at most 20 pages within 30 seconds. Apply re-reads the provider and requires the exact preview digest. Missing jobs remain unchanged; existing locally closed jobs stay closed. No provider data writes or background polling.",
        "security": [{ "oauth2": ["operations:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["provider", "action"],
                "anyOf": [
                  {
                    "required": ["useSavedConnection"],
                    "properties": { "useSavedConnection": { "const": true } }
                  },
                  { "required": ["accessToken"] }
                ],
                "properties": {
                  "useSavedConnection": {
                    "type": "boolean",
                    "description": "Use only the authenticated owner's saved provider source and grant."
                  },
                  "provider": { "enum": ["servicem8", "simpro"] },
                  "action": { "enum": ["preview", "apply"] },
                  "accessToken": { "type": "string", "writeOnly": true, "maxLength": 8192 },
                  "origin": {
                    "type": "string",
                    "description": "Required for Simpro with a caller-supplied token: exact HTTPS build origin on simprosuite.com or simprocloud.com. Ignored for saved connections."
                  },
                  "companyId": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Required for Simpro with a caller-supplied token. Ignored for saved connections."
                  },
                  "digest": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$",
                    "description": "Required when action is apply."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview jobs and digest, or imported row count after confirmation. Count includes updates and idempotent retries."
          },
          "400": { "description": "Invalid provider, destination, token or confirmation." },
          "401": { "description": "Fleetkeep authorisation required." },
          "403": { "description": "Fleet plan or scope required." },
          "409": {
            "description": "Reconnect provider, changed preview, conflicting reference or read limit reached."
          },
          "429": { "description": "Provider rate limit reached. No automatic retry." },
          "502": {
            "description": "Provider unavailable or unsupported response. No partial import applied."
          }
        }
      }
    },
    "/api/v1/jobs": {
      "get": {
        "operationId": "listFleetJobs",
        "summary": "List the fleet owner's jobs. Requires an active Fleet plan.",
        "security": [{ "oauth2": ["operations:read"] }],
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }
        ],
        "responses": {
          "200": { "description": "jobs array and hasMore flag; at most 250 matches" }
        }
      },
      "post": {
        "operationId": "saveFleetJob",
        "summary": "Save a shared job reference, or close/reopen a job owned by the caller.",
        "security": [{ "oauth2": ["operations:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": ["action", "reference", "title"],
                    "properties": {
                      "action": { "const": "save" },
                      "reference": { "type": "string", "maxLength": 120 },
                      "title": { "type": "string", "maxLength": 120 }
                    }
                  },
                  {
                    "type": "object",
                    "required": ["action", "id", "status"],
                    "properties": {
                      "action": { "const": "status" },
                      "id": { "type": "string", "format": "uuid" },
                      "status": { "enum": ["active", "closed"] }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved job. Reusing a reference updates the title without reopening it."
          }
        }
      }
    },
    "/api/v1/costs": {
      "get": {
        "operationId": "getRunningCosts",
        "summary": "Recorded GBP costs by vehicle, with missing service amounts and excluded currencies flagged.",
        "security": [{ "oauth2": ["operations:read"] }],
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": {
            "description": "Vehicle totals and latest 250 additional costs. Date range is limited to one year. Not proof of payment."
          }
        }
      },
      "post": {
        "operationId": "recordFleetExpense",
        "summary": "Record a GBP expense. Keep the same UUID and payload on retries.",
        "security": [{ "oauth2": ["operations:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["id", "vehicleId", "incurredOn", "category", "description", "amount"],
                "properties": {
                  "id": { "type": "string", "format": "uuid" },
                  "vehicleId": { "type": "string", "format": "uuid" },
                  "incurredOn": { "type": "string", "format": "date" },
                  "category": { "enum": ["fuel", "insurance", "repair", "parking", "other"] },
                  "description": { "type": "string", "maxLength": 240 },
                  "amount": {
                    "type": "string",
                    "description": "GBP decimal amount, up to two decimal places; negative for refunds."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Recorded expense" },
          "409": { "description": "Submission UUID already used with different details" }
        }
      }
    },
    "/api/v1/driver-workspace/{id}/jobs": {
      "get": {
        "operationId": "listDriverJobs",
        "summary": "Active jobs for the caller's accepted driver membership. Never exposes company costs.",
        "security": [{ "oauth2": ["operations:read"] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          },
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }
        ],
        "responses": {
          "200": {
            "description": "jobs array with id, reference and title; hasMore flags additional matches"
          }
        }
      }
    },
    "/api/v1/vehicles": {
      "get": {
        "tags": ["Vehicles"],
        "summary": "List the authorised user's vehicles",
        "description": "Returns every vehicle on the user's account, ordered by createdAt descending.",
        "operationId": "listVehicles",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "responses": {
          "200": {
            "description": "Vehicle list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["vehicles", "truncated"],
                  "properties": {
                    "vehicles": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Vehicle" }
                    },
                    "truncated": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Vehicles"],
        "summary": "Add a vehicle by registration",
        "description": "Adds a vehicle to the authorised user's account. Server triggers a DVLA Vehicle Enquiry Service lookup to populate make, model, year, fuel, MOT due date and tax due date. Insurance, last service and service interval are taken from the request body if supplied.",
        "operationId": "addVehicle",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AddVehicleInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vehicle created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["id"],
                  "properties": {
                    "id": { "type": "string", "format": "uuid" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": {
            "description": "A vehicle with this registration already exists on the user's account.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": {
            "description": "DVLA upstream lookup failed.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/api/v1/vehicles/search": {
      "get": {
        "tags": ["Vehicles"],
        "summary": "Find a vehicle by registration, name, make or model",
        "description": "Search only the signed-in user's vehicles. Use this before recording a service when the user gives a registration rather than a vehicle ID. Results are capped; if limit_reached is true, narrow the search before choosing a vehicle.",
        "operationId": "searchVehicles",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 2, "maxLength": 120 },
            "description": "At least two characters from the registration, label, make or model."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }
          }
        ],
        "responses": {
          "200": { "description": "Up to the requested number of matching, account-owned vehicles; limit_reached means more may exist." },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Vehicle UUID."
        }
      ],
      "get": {
        "tags": ["Vehicles"],
        "summary": "Get a single vehicle",
        "operationId": "getVehicle",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "responses": {
          "200": {
            "description": "Vehicle detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["vehicle"],
                  "properties": {
                    "vehicle": { "$ref": "#/components/schemas/Vehicle" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "tags": ["Vehicles"],
        "summary": "Update mutable vehicle fields",
        "description": "Patch semantics: only fields present in the body are touched. `null` explicitly clears a value; missing keys leave the existing value untouched. Label, insuranceDueDate, lastServiceDate, lastServiceMileage, serviceIntervalMonths, serviceIntervalDays, operationalStatus, assignedDriverName, assignedDriverContact and statusNotes are mutable. DVLA-sourced fields cannot be patched and refresh from DVLA on a server-side schedule.",
        "operationId": "updateVehicle",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateVehiclePatch" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Patch applied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok"],
                  "properties": { "ok": { "type": "boolean", "const": true } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "delete": {
        "tags": ["Vehicles"],
        "summary": "Remove a vehicle",
        "description": "Two-step destructive action. The first request verifies ownership and returns 409 confirmation_required with a five-minute token. Retry with that token in X-Fleetkeep-Confirmation. The token is bound to the user, access token, action, vehicle and current vehicle version; any vehicle update invalidates it.",
        "operationId": "deleteVehicle",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "parameters": [
          {
            "name": "X-Fleetkeep-Confirmation",
            "in": "header",
            "required": false,
            "schema": { "type": "string" },
            "description": "Confirmation token returned by the immediately preceding unconfirmed DELETE request."
          }
        ],
        "responses": {
          "204": { "description": "Vehicle deleted." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": {
            "description": "Confirmation is required, invalid, expired or invalidated by a vehicle update.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ActionConfirmationRequired" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/checks": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Vehicle UUID."
        }
      ],
      "get": {
        "tags": ["Equipment"],
        "summary": "List a vehicle's equipment lifecycle records",
        "description": "Returns current and historical equipment for an owned vehicle. `active` is true only when the record is not removed and has no removal date.",
        "operationId": "listVehicleEquipment",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "responses": {
          "200": {
            "description": "Equipment lifecycle records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["equipment"],
                  "properties": {
                    "equipment": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/EquipmentRecord" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Equipment"],
        "summary": "Add equipment to a vehicle",
        "description": "Creates an equipment lifecycle record for an owned vehicle.",
        "operationId": "addVehicleEquipment",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentInput" } }
          }
        },
        "responses": {
          "201": {
            "description": "Equipment created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["id"],
                  "properties": { "id": { "type": "string", "format": "uuid" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": {
            "description": "A current record already exists for this equipment preset.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "tags": ["Equipment"],
        "summary": "Update an equipment record",
        "description": "Updates an owned equipment record. Current equipment cannot be ended through this operation; use the confirmed lifecycle-removal operation. Historical equipment cannot be reactivated: attempts return `equipment_history_immutable`.",
        "operationId": "updateVehicleEquipment",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EquipmentUpdateInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Equipment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok"],
                  "properties": { "ok": { "type": "boolean", "const": true } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": {
            "description": "Use the confirmation-gated lifecycle removal operation to end current equipment, keep historical equipment historical, or resolve a conflicting current preset record. Stable errors include `use_equipment_lifecycle_removal`, `equipment_history_immutable` and `equipment_preset_already_active`.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "delete": {
        "tags": ["Equipment"],
        "summary": "End an equipment lifecycle",
        "description": "Preserves the record as history; it does not hard-delete it. First call with the record ID and removal date returns a five-minute confirmation token. Retry the identical request with X-Fleetkeep-Confirmation. The token is bound to the user, bearer token, equipment version and removal date.",
        "operationId": "removeVehicleEquipment",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "parameters": [
          {
            "name": "X-Fleetkeep-Confirmation",
            "in": "header",
            "required": false,
            "schema": { "type": "string" },
            "description": "Confirmation token returned by the immediately preceding request."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["id", "removedOn"],
                "properties": {
                  "id": { "type": "string", "format": "uuid" },
                  "removedOn": { "type": "string", "format": "date" }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Equipment moved to lifecycle history.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EquipmentRemovalResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": {
            "description": "Confirmation is required, invalid, expired or invalidated.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ActionConfirmationRequired" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/equipment/templates": {
      "get": {
        "tags": ["Equipment"],
        "summary": "List stable equipment presets",
        "operationId": "listEquipmentTemplates",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "responses": {
          "200": {
            "description": "Equipment preset catalogue.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["presets"],
                  "properties": {
                    "presets": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/EquipmentPreset" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Equipment"],
        "summary": "Preview equipment presets across owned vehicles",
        "description": "Read-only preview. Existing current presets are reported as skipped and never overwritten.",
        "operationId": "previewEquipmentTemplate",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EquipmentTemplateInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview result and digest required to apply the identical canonical selection.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EquipmentTemplateResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "put": {
        "tags": ["Equipment"],
        "summary": "Apply previewed equipment presets across owned vehicles",
        "description": "Applies the identical canonical selection using its preview digest. Existing current presets are skipped and never overwritten.",
        "operationId": "applyEquipmentTemplate",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EquipmentTemplateApplyInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Applied template result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EquipmentTemplateResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": {
            "description": "Apply did not include the digest for the identical preview selection.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/bulk": {
      "post": {
        "tags": ["Vehicles"],
        "summary": "Bulk add vehicles by registration",
        "description": "Add up to 50 vehicles in one call. Each registration is processed sequentially; partial success is reported via separate `created` and `errors` arrays.",
        "operationId": "bulkAddVehicles",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["registrations"],
                "properties": {
                  "registrations": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": { "type": "string", "example": "BD15 KFG" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk add result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["created", "errors"],
                  "properties": {
                    "created": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["id", "registration"],
                        "properties": {
                          "id": { "type": "string", "format": "uuid" },
                          "registration": { "type": "string" }
                        }
                      }
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["reg", "reason"],
                        "properties": {
                          "reg": { "type": "string" },
                          "reason": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/imports/vehicles/preview": {
      "post": {
        "tags": ["Imports"],
        "summary": "Preview a fleet spreadsheet without writing data",
        "operationId": "previewVehicleImport",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SpreadsheetPayload" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read-only preview with a content digest required for apply.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VehicleImportPreview" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/imports/vehicles/apply": {
      "post": {
        "tags": ["Imports"],
        "summary": "Apply the exact previously previewed spreadsheet",
        "description": "Requires the identical spreadsheet bytes, the digest returned by preview and an 8-128 character idempotency key. Existing vehicle dates and current equipment are not overwritten.",
        "operationId": "applyVehicleImport",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ApplySpreadsheetPayload" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import outcomes. A repeated idempotency key returns the recorded result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VehicleImportResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": {
            "description": "The confirmation digest does not match the uploaded bytes.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/operations/walkaround-definition": {
      "get": {
        "tags": ["Maintenance"],
        "summary": "Get the current walkaround definition",
        "operationId": "getWalkaroundDefinition",
        "security": [{ "oauth2": ["operations:read"] }],
        "responses": {
          "200": {
            "description": "Closed, versioned walkaround groups and items",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalkaroundDefinition" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/operations/walkaround-summary": {
      "get": {
        "tags": ["Maintenance"],
        "summary": "Get today's completed fleet walkarounds",
        "description": "Returns the definition and distinct vehicle IDs with recorded walkarounds today in Europe/London. Account-scoped and not cached; completion does not certify roadworthiness.",
        "operationId": "getWalkaroundSummary",
        "security": [{ "oauth2": ["operations:read"] }],
        "responses": {
          "200": {
            "description": "Today's fleet check summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["definition", "completedVehicleIds"],
                  "properties": {
                    "definition": { "$ref": "#/components/schemas/WalkaroundDefinition" },
                    "completedVehicleIds": {
                      "type": "array",
                      "uniqueItems": true,
                      "items": { "type": "string", "format": "uuid" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/walkarounds": {
      "parameters": [{ "$ref": "#/components/parameters/VehicleId" }],
      "get": {
        "tags": ["Maintenance"],
        "summary": "List bounded walkarounds and scoped evidence links",
        "operationId": "listWalkarounds",
        "security": [{ "oauth2": ["operations:read"] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740990, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded walkaround history; no storage keys or private object URLs",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/WalkaroundHistory" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Maintenance"],
        "summary": "Submit an idempotent walkaround with optional evidence",
        "description": "submissionId is idempotent. Consequential non-mobile submissions return 409 until the exact canonical payload and uploaded bytes are confirmed. The signed fleetkeep-mobile client retains its one-step flow.",
        "operationId": "submitWalkaround",
        "security": [{ "oauth2": ["operations:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/OptionalConfirmation" }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["payload"],
                "properties": {
                  "payload": {
                    "type": "string",
                    "contentMediaType": "application/json",
                    "contentSchema": { "$ref": "#/components/schemas/WalkaroundSubmission" },
                    "description": "JSON WalkaroundSubmission object; unknown fields are rejected."
                  },
                  "media": {
                    "type": "array",
                    "maxItems": 5,
                    "items": {
                      "oneOf": [
                        {
                          "type": "string",
                          "format": "binary",
                          "contentMediaType": "image/jpeg",
                          "maxLength": 10485760
                        },
                        {
                          "type": "string",
                          "format": "binary",
                          "contentMediaType": "image/png",
                          "maxLength": 10485760
                        },
                        {
                          "type": "string",
                          "format": "binary",
                          "contentMediaType": "image/webp",
                          "maxLength": 10485760
                        },
                        {
                          "type": "string",
                          "format": "binary",
                          "contentMediaType": "video/mp4",
                          "maxLength": 10485760
                        },
                        {
                          "type": "string",
                          "format": "binary",
                          "contentMediaType": "video/quicktime",
                          "maxLength": 10485760
                        },
                        {
                          "type": "string",
                          "format": "binary",
                          "contentMediaType": "video/webm",
                          "maxLength": 10485760
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalkaroundSubmissionResult" }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalkaroundSubmissionResult" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/api/v1/vehicles/{id}/walkarounds/{checkId}/media/{mediaId}": {
      "get": {
        "tags": ["Maintenance"],
        "summary": "Read tenant-scoped walkaround evidence",
        "operationId": "getWalkaroundEvidence",
        "security": [{ "oauth2": ["operations:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/VehicleId" },
          {
            "name": "checkId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Private evidence bytes",
            "content": {
              "image/jpeg": { "schema": { "type": "string", "format": "binary" } },
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/webp": { "schema": { "type": "string", "format": "binary" } },
              "video/mp4": { "schema": { "type": "string", "format": "binary" } },
              "video/quicktime": { "schema": { "type": "string", "format": "binary" } },
              "video/webm": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/api/v1/vehicles/{id}/documents": {
      "parameters": [{ "$ref": "#/components/parameters/VehicleId" }],
      "get": {
        "tags": ["Vehicles"],
        "summary": "List private vehicle document records",
        "operationId": "listVehicleDocuments",
        "security": [{ "oauth2": ["documents:read"] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740990, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded records and executable pagination state; no storage keys",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VehicleDocumentList" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Vehicles"],
        "summary": "Create a private metadata record or upload a private document",
        "operationId": "createVehicleDocument",
        "security": [{ "oauth2": ["documents:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VehicleDocumentInput" }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["metadata"],
                "properties": {
                  "metadata": {
                    "type": "string",
                    "contentMediaType": "application/json",
                    "contentSchema": { "$ref": "#/components/schemas/VehicleDocumentInput" },
                    "description": "JSON VehicleDocumentInput"
                  },
                  "file": {
                    "oneOf": [
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "application/pdf",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "image/jpeg",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "image/png",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "image/webp",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "application/msword",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "application/vnd.ms-excel",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                        "maxLength": 10485760
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Private record created with driverVisible false",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["record"],
                  "properties": { "record": { "$ref": "#/components/schemas/VehicleDocument" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/api/v1/vehicles/{id}/documents/{documentId}/download": {
      "get": {
        "tags": ["Vehicles"],
        "summary": "Download a tenant-scoped private vehicle document",
        "operationId": "downloadVehicleDocument",
        "security": [{ "oauth2": ["documents:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/VehicleId" },
          {
            "name": "documentId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Private document bytes",
            "content": {
              "application/pdf": { "schema": { "type": "string", "format": "binary" } },
              "image/jpeg": { "schema": { "type": "string", "format": "binary" } },
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/webp": { "schema": { "type": "string", "format": "binary" } },
              "application/msword": { "schema": { "type": "string", "format": "binary" } },
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": { "type": "string", "format": "binary" }
              },
              "application/vnd.ms-excel": { "schema": { "type": "string", "format": "binary" } },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/api/v1/vehicles/{id}/photo": {
      "parameters": [{ "$ref": "#/components/parameters/VehicleId" }],
      "get": {
        "tags": ["Vehicles"],
        "summary": "Read the private current vehicle photo",
        "operationId": "getVehiclePhoto",
        "security": [{ "oauth2": ["vehicles:read"] }],
        "responses": {
          "200": {
            "description": "Private image bytes",
            "content": {
              "image/jpeg": { "schema": { "type": "string", "format": "binary" } },
              "image/png": { "schema": { "type": "string", "format": "binary" } },
              "image/webp": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      },
      "post": {
        "tags": ["Vehicles"],
        "summary": "Replace the private current vehicle photo",
        "operationId": "uploadVehiclePhoto",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["photo"],
                "properties": {
                  "photo": {
                    "oneOf": [
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "image/jpeg",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "image/png",
                        "maxLength": 10485760
                      },
                      {
                        "type": "string",
                        "format": "binary",
                        "contentMediaType": "image/webp",
                        "maxLength": 10485760
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Photo uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["photo"],
                  "properties": { "photo": { "$ref": "#/components/schemas/VehiclePhoto" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      },
      "delete": {
        "tags": ["Vehicles"],
        "summary": "Remove the private current vehicle photo",
        "description": "The signed fleetkeep-mobile client may delete after its native destructive confirmation. Other clients require the version-bound confirmation header.",
        "operationId": "deleteVehiclePhoto",
        "security": [{ "oauth2": ["vehicles:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/OptionalConfirmation" }],
        "responses": {
          "200": {
            "description": "Closed removed boolean",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VehiclePhotoRemoval" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/service-schedules": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned vehicle UUID."
        }
      ],
      "get": {
        "tags": ["Maintenance"],
        "summary": "List source-backed service schedules",
        "description": "Returns provider or operator schedule snapshots separately from Fleetkeep's calculated status. Results never certify roadworthiness.",
        "operationId": "listServiceSchedules",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded schedule history, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["schedules", "hasMore", "nextOffset"],
                  "properties": {
                    "schedules": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ServiceSchedule" }
                    },
                    "hasMore": { "type": "boolean" },
                    "nextOffset": { "type": ["integer", "null"], "minimum": 0 }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/service-evidence-requests": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned vehicle UUID."
        }
      ],
      "get": {
        "tags": ["Maintenance"],
        "summary": "List service-evidence requests",
        "description": "Returns recorded recipient, delivery, chasing and human-review state without sending or changing anything.",
        "operationId": "listServiceEvidenceRequests",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded evidence-request history, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["requests", "hasMore", "nextOffset"],
                  "properties": {
                    "requests": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ServiceEvidenceRequest" }
                    },
                    "hasMore": { "type": "boolean" },
                    "nextOffset": { "type": ["integer", "null"], "minimum": 0 }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/contacts": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned vehicle UUID."
        },
        {
          "name": "requestId",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned evidence-request UUID."
        }
      ],
      "get": {
        "tags": ["Maintenance"],
        "summary": "Get the service-evidence timeline",
        "description": "Returns the recorded request plus append-only contact events and original customer submissions. Customer evidence remains an assessment until a human review is recorded.",
        "operationId": "getServiceEvidenceTimeline",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded evidence timeline.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["request", "contacts", "submissions"],
                  "properties": {
                    "request": { "$ref": "#/components/schemas/ServiceEvidenceRequest" },
                    "contacts": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ServiceEvidenceContact" }
                    },
                    "submissions": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ServiceEvidenceSubmission" }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/service-records": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned vehicle UUID."
        }
      ],
      "get": {
        "tags": ["Maintenance"],
        "summary": "List preserved service-record history",
        "operationId": "listServiceRecords",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A bounded page of owned service records, newest service date first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["records", "hasMore", "nextOffset"],
                  "properties": {
                    "records": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ServiceRecord" }
                    },
                    "hasMore": { "type": "boolean" },
                    "nextOffset": {
                      "type": ["integer", "null"],
                      "minimum": 0,
                      "maximum": 9007199254740991
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Maintenance"],
        "summary": "Create a service record",
        "description": "Two-step operator-confirmed write for non-mobile clients. First send the proposed record with an 8-128 character Idempotency-Key; Fleetkeep returns confirmation_required. Retry the identical body and key with X-Fleetkeep-Confirmation. Safe retries return the original record with replay true. The signed Fleetkeep mobile client uses its native review flow. updateServiceReminder defaults to true.",
        "operationId": "createServiceRecord",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" },
          { "$ref": "#/components/parameters/FleetkeepConfirmation" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRecordInput" } }
          }
        },
        "responses": {
          "200": {
            "description": "An idempotent retry returned the previously created record.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ServiceRecordCreateEnvelope" }
              }
            }
          },
          "201": {
            "description": "Service record created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ServiceRecordCreateEnvelope" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/service-records/{recordId}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" }
        },
        {
          "name": "recordId",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" }
        }
      ],
      "get": {
        "tags": ["Maintenance"],
        "summary": "Get one service record",
        "operationId": "getServiceRecord",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "responses": {
          "200": {
            "description": "Owned service record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["record"],
                  "properties": { "record": { "$ref": "#/components/schemas/ServiceRecord" } },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "put": {
        "tags": ["Maintenance"],
        "summary": "Replace a historical service record",
        "description": "Requires x-fleetkeep-confirmation from the initial 409. Confirmation binds subject, token JTI, action, record ID and current updatedAt.",
        "operationId": "updateServiceRecord",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/FleetkeepConfirmation" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRecordInput" } }
          }
        },
        "responses": {
          "200": {
            "description": "Updated and audited record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["record"],
                  "properties": { "record": { "$ref": "#/components/schemas/ServiceRecord" } },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "delete": {
        "tags": ["Maintenance"],
        "summary": "Delete a historical service record",
        "description": "Requires x-fleetkeep-confirmation and fails closed after a version change or deletion.",
        "operationId": "deleteServiceRecord",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/FleetkeepConfirmation" }],
        "responses": {
          "204": { "description": "Deleted and audited." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/operations/maintenance": {
      "get": {
        "tags": ["Maintenance"],
        "summary": "List maintenance tasks and recent completed history",
        "operationId": "listMaintenance",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "responses": {
          "200": {
            "description": "Owned open and recent completed maintenance tasks.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceList" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/vehicles/{id}/maintenance": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned vehicle UUID."
        }
      ],
      "post": {
        "tags": ["Maintenance"],
        "summary": "Create a maintenance task for an owned vehicle",
        "operationId": "createMaintenance",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/MaintenanceInput" },
                  { "$ref": "#/components/schemas/ForecastMaintenanceInput" }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Task created and audited.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["event"],
                  "properties": { "event": { "$ref": "#/components/schemas/MaintenanceEvent" } },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/operations/maintenance/{eventId}": {
      "parameters": [
        {
          "name": "eventId",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "Owned non-defect maintenance event UUID."
        }
      ],
      "get": {
        "tags": ["Maintenance"],
        "summary": "Get an owned maintenance task",
        "operationId": "getMaintenance",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "responses": {
          "200": {
            "description": "Maintenance task or preserved completed history.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["event"],
                  "properties": { "event": { "$ref": "#/components/schemas/MaintenanceEvent" } },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "tags": ["Maintenance"],
        "summary": "Update an owned open maintenance task",
        "description": "Completed history is immutable and returns not_found.",
        "operationId": "updateMaintenance",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceInput" } }
          }
        },
        "responses": {
          "200": {
            "description": "Task updated and audited.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["event"],
                  "properties": { "event": { "$ref": "#/components/schemas/MaintenanceEvent" } },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "delete": {
        "tags": ["Maintenance"],
        "summary": "Cancel an owned open maintenance task",
        "description": "Two-step destructive action. First request returns confirmation_required; retry with X-Fleetkeep-Confirmation. Completed history and defects are never deleted.",
        "operationId": "deleteMaintenance",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/ActionConfirmation" }],
        "responses": {
          "204": { "description": "Open task deleted and cancellation audited." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/operations/defects": {
      "get": {
        "tags": ["Defects"],
        "summary": "List owned open and recent completed defects",
        "operationId": "listDefects",
        "security": [{ "oauth2": ["operations:read"] }],
        "responses": {
          "200": {
            "description": "Defect list.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DefectList" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Defects"],
        "summary": "Report a defect for an owned vehicle",
        "operationId": "createDefect",
        "security": [{ "oauth2": ["operations:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/DefectInput" } }
          }
        },
        "responses": {
          "201": {
            "description": "Defect created and audited.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["defect"],
                  "properties": { "defect": { "$ref": "#/components/schemas/DefectEvent" } },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/agent/operations/maintenance/{eventId}/complete": {
      "parameters": [
        {
          "name": "eventId",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" }
        },
        { "$ref": "#/components/parameters/ActionConfirmation" }
      ],
      "post": {
        "tags": ["Maintenance"],
        "summary": "Complete an owned open maintenance task agentically",
        "description": "Two-step version-bound action. A recurring task creates at most one successor during the confirmed atomic completion. Forecast tasks require actual completedDate and completedMileage in both requests; confirmation is bound to those readings. The next estimate retains the saved annual mileage, interval and reminder timing.",
        "operationId": "completeMaintenance",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "requestBody": {
          "description": "Required only for mileage forecasts.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["completedDate", "completedMileage"],
                "properties": {
                  "completedDate": { "type": "string", "format": "date" },
                  "completedMileage": { "type": "integer", "minimum": 0 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Confirmed completion result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MaintenanceCompletion" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/agent/operations/defects/{eventId}/complete": {
      "parameters": [
        {
          "name": "eventId",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" }
        },
        { "$ref": "#/components/parameters/ActionConfirmation" }
      ],
      "post": {
        "tags": ["Defects"],
        "summary": "Complete an owned open defect agentically",
        "description": "Two-step version-bound action. Completion preserves defect history and replay returns not_found.",
        "operationId": "completeDefect",
        "security": [{ "oauth2": ["operations:write"] }],
        "responses": {
          "200": {
            "description": "Defect completed and audited.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DefectCompletion" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/settings/reminders": {
      "get": {
        "tags": ["Reminders"],
        "operationId": "getReminderSettings",
        "security": [{ "oauth2": ["reminders:read"] }],
        "responses": {
          "200": {
            "description": "Settings",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ReminderSettings" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "put": {
        "tags": ["Reminders"],
        "operationId": "updateReminderSettings",
        "security": [{ "oauth2": ["reminders:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReminderSettingsWrite" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ReminderSettings" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/v1/vehicles/{id}/reminders": {
      "get": {
        "tags": ["Reminders"],
        "operationId": "getVehicleReminderRecipients",
        "security": [{ "oauth2": ["reminders:read"] }],
        "parameters": [{ "$ref": "#/components/parameters/VehicleId" }],
        "responses": {
          "200": {
            "description": "Vehicle reminder recipients",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VehicleReminderSettings" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "put": {
        "tags": ["Reminders"],
        "operationId": "replaceVehicleReminderRecipients",
        "security": [{ "oauth2": ["reminders:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/VehicleId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/VehicleReminderRecipientsWrite" },
                  { "$ref": "#/components/schemas/ReminderIntervalsWrite" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated recipients",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/VehicleReminderRecipients" },
                    { "$ref": "#/components/schemas/ReminderIntervals" }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      },
      "post": {
        "tags": ["Reminders"],
        "operationId": "createMobileVehicleReminderRecipient",
        "description": "Compatibility operation available only to the verified Fleetkeep mobile client. It adds the contact, assigns it to this vehicle and attempts its consent email.",
        "security": [{ "oauth2": ["reminders:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/VehicleId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } }
          }
        },
        "responses": {
          "201": {
            "description": "Recipient assignment and confirmation outcome",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VehicleReminderMobileResult" }
              }
            }
          },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" }
        }
      }
    },
    "/api/v1/contacts": {
      "get": {
        "tags": ["Reminders"],
        "operationId": "listContacts",
        "security": [{ "oauth2": ["reminders:read"] }],
        "responses": {
          "200": {
            "description": "Contacts",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } }
            }
          }
        }
      },
      "post": {
        "tags": ["Reminders"],
        "operationId": "createContact",
        "security": [{ "oauth2": ["reminders:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } }
          }
        },
        "responses": {
          "200": {
            "description": "Existing contact replayed without sending email",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } }
            }
          },
          "201": {
            "description": "Created without sending email",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/v1/contacts/{id}": {
      "delete": {
        "tags": ["Reminders"],
        "operationId": "deleteContact",
        "security": [{ "oauth2": ["reminders:write"] }],
        "parameters": [
          { "$ref": "#/components/parameters/ContactId" },
          { "$ref": "#/components/parameters/ActionConfirmation" }
        ],
        "responses": {
          "204": { "description": "Deleted" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" }
        }
      }
    },
    "/api/v1/contacts/{id}/verification/preview": {
      "post": {
        "tags": ["Reminders"],
        "operationId": "previewContactVerification",
        "security": [{ "oauth2": ["reminders:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/ContactId" }],
        "responses": {
          "200": {
            "description": "Five-minute confirmation",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/OutboundPreview" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/contacts/{id}/verification/send": {
      "post": {
        "tags": ["Reminders"],
        "operationId": "sendContactVerification",
        "security": [{ "oauth2": ["reminders:write"] }],
        "parameters": [
          { "$ref": "#/components/parameters/ContactId" },
          { "$ref": "#/components/parameters/ActionConfirmation" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": {
          "200": {
            "description": "Sent or replayed",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/OutboundResult" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "502": { "$ref": "#/components/responses/ProviderFailure" }
        }
      }
    },
    "/api/v1/bookings": {
      "get": {
        "tags": ["Bookings"],
        "operationId": "listBookings",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "responses": {
          "200": {
            "description": "Bookings",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/BookingList" } }
            }
          }
        }
      },
      "post": {
        "tags": ["Bookings"],
        "operationId": "createBooking",
        "description": "Derives task, vehicle and category from an owned open maintenance event. It does not send email.",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/BookingWrite" } }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay of the saved booking",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/BookingEnvelope" } }
            }
          },
          "201": {
            "description": "Saved",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/BookingEnvelope" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" }
        }
      }
    },
    "/api/v1/bookings/{id}": {
      "get": {
        "tags": ["Bookings"],
        "operationId": "getBooking",
        "security": [{ "oauth2": ["maintenance:read"] }],
        "parameters": [{ "$ref": "#/components/parameters/BookingId" }],
        "responses": {
          "200": {
            "description": "Booking",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/BookingEnvelope" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" }
        }
      },
      "patch": {
        "tags": ["Bookings"],
        "operationId": "updateBookingStatus",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/BookingId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/BookingStatusWrite" } }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BookingStatusEnvelope" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" }
        }
      }
    },
    "/api/v1/bookings/{id}/garage-email/preview": {
      "post": {
        "tags": ["Bookings"],
        "operationId": "previewGarageEmail",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/BookingId" }],
        "responses": {
          "200": {
            "description": "Five-minute confirmation",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/OutboundPreview" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" }
        }
      }
    },
    "/api/v1/bookings/{id}/garage-email/send": {
      "post": {
        "tags": ["Bookings"],
        "operationId": "sendGarageEmail",
        "security": [{ "oauth2": ["maintenance:write"] }],
        "parameters": [
          { "$ref": "#/components/parameters/BookingId" },
          { "$ref": "#/components/parameters/ActionConfirmation" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "responses": {
          "200": {
            "description": "Sent or replayed",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/OutboundResult" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/ConfirmationConflict" },
          "502": { "$ref": "#/components/responses/ProviderFailure" }
        }
      }
    },
    "/api/v1/operations/tolls": {
      "get": {
        "tags": ["Tolls"],
        "summary": "Read the current toll and clean-air action view",
        "description": "Returns recorded spend and inferred crossing reviews. Inferred crossings never confirm liability or payment.",
        "operationId": "getTollOperations",
        "security": [{ "oauth2": ["operations:read"] }],
        "responses": {
          "200": {
            "description": "Toll action summary",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TollOperations" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Tolls"],
        "summary": "Confirm or dismiss one pending inferred crossing",
        "description": "Confirmation records the crossing review only. It does not confirm liability, payment or the estimated amount.",
        "operationId": "reviewTollCrossing",
        "security": [{ "oauth2": ["operations:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/TollReviewWrite" } }
          }
        },
        "responses": {
          "200": {
            "description": "Reviewed",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TollReviewResult" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/tolls/accounts": {
      "get": {
        "tags": ["Tolls"],
        "summary": "List owned toll and clean-air cover records",
        "operationId": "listTollAccounts",
        "security": [{ "oauth2": ["tolls:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/ListLimit" },
          { "$ref": "#/components/parameters/ListOffset" },
          { "$ref": "#/components/parameters/OptionalVehicleId" }
        ],
        "responses": {
          "200": {
            "description": "Owned account records",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TollAccountList" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Tolls"],
        "summary": "Create an owned toll or clean-air cover record",
        "description": "Stores the customer's record only. It does not create an account or initiate a payment with the provider.",
        "operationId": "createTollAccount",
        "security": [{ "oauth2": ["tolls:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/TollAccountWrite" } }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TollAccountEnvelope" }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TollAccountEnvelope" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/tolls/transactions": {
      "get": {
        "tags": ["Tolls"],
        "summary": "List owned recorded toll and clean-air charges",
        "operationId": "listTollTransactions",
        "security": [{ "oauth2": ["tolls:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/ListLimit" },
          { "$ref": "#/components/parameters/ListOffset" },
          { "$ref": "#/components/parameters/OptionalVehicleId" }
        ],
        "responses": {
          "200": {
            "description": "Owned recorded charges",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TollTransactionList" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Tolls"],
        "summary": "Record an owned toll or clean-air charge",
        "description": "Records customer-supplied spend only. It does not initiate, settle or verify payment.",
        "operationId": "createTollTransaction",
        "security": [{ "oauth2": ["tolls:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TollTransactionWrite" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TollTransactionEnvelope" }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TollTransactionEnvelope" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/tolls/imports/preview": {
      "post": {
        "tags": ["Tolls", "Imports"],
        "summary": "Preview a bounded fleet toll statement without writing",
        "operationId": "previewTollImport",
        "security": [{ "oauth2": ["tolls:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/TollImportPayload" } }
          }
        },
        "responses": {
          "200": {
            "description": "Read-only preview bound to the exact CSV bytes",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TollImportPreview" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/tolls/imports/apply": {
      "post": {
        "tags": ["Tolls", "Imports"],
        "summary": "Apply the exact previously previewed toll statement",
        "description": "Requires the same CSV bytes, the preview digest and an Idempotency-Key. At most 500 charge rows are accepted.",
        "operationId": "applyTollImport",
        "security": [{ "oauth2": ["tolls:write"] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TollImportApplyPayload" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TollImportResult" } }
            }
          },
          "201": {
            "description": "Applied",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TollImportResult" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/operations/tracking": {
      "get": {
        "tags": ["Tracking"],
        "summary": "List fleet tracking snapshots and connection states",
        "description": "Returns stored readings only. A vehicle without a connected or current provider remains in the list with nullable tracking fields.",
        "operationId": "listTrackingSnapshots",
        "security": [{ "oauth2": ["operations:read"] }],
        "responses": {
          "200": {
            "description": "Tenant-scoped vehicle tracking states",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["vehicles"],
                  "properties": {
                    "vehicles": {
                      "type": "array",
                      "maxItems": 1000,
                      "items": { "$ref": "#/components/schemas/TrackingVehicle" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    },
    "/api/v1/operations/tracking/{vehicleId}/route": {
      "get": {
        "tags": ["Tracking"],
        "summary": "Fetch authorised Wex route, trip, fuel and diagnostic data",
        "description": "Calls Wex only after tenant ownership and an active Wex link are proven. A successful response proves only that this request returned provider data; it does not claim general account feed availability.",
        "operationId": "getWexRouteHistory",
        "security": [{ "oauth2": ["operations:read"] }],
        "parameters": [
          {
            "name": "vehicleId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["today", "yesterday", "7d"], "default": "today" }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded provider response",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TrackingRoute" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/ProviderFailure" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    },
    "/api/v1/setup": {
      "get": {
        "tags": ["Account"],
        "summary": "Check fleet setup and the next onboarding step",
        "description": "Read this first when setting up Fleetkeep. Available before purchase. Returns subscription access, trial end, vehicle count, email consent and secure website links. Does not start a trial, take payment or change records. Keep existing subscriptions; never ask for card details. Preview supplied spreadsheets and obtain confirmation before applying. Re-read after each website step.",
        "operationId": "getSetupStatus",
        "security": [{ "oauth2": ["profile:read"] }],
        "responses": {
          "200": {
            "description": "Account-scoped setup status and next action",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "nextStep",
                    "vehicleCount",
                    "canUseApi",
                    "billing",
                    "emailRemindersEnabled",
                    "nextAction",
                    "paymentNote",
                    "links"
                  ],
                  "properties": {
                    "nextStep": {
                      "type": "string",
                      "enum": ["plan", "fleet_access", "vehicles", "reminders", "review"]
                    },
                    "vehicleCount": { "type": "integer", "minimum": 0 },
                    "canUseApi": { "type": "boolean" },
                    "billing": {
                      "type": "object",
                      "description": "Current active, plan, status, source, trialEligible, trialEndsAt, vehicleLimit and paymentMethodAdded values. No payment credentials."
                    },
                    "emailRemindersEnabled": { "type": "boolean" },
                    "nextAction": { "type": "string" },
                    "paymentNote": { "type": "string" },
                    "links": {
                      "type": "object",
                      "additionalProperties": { "type": "string", "format": "uri" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/profile": {
      "get": {
        "tags": ["Account"],
        "summary": "Read the authorised user's Fleetkeep profile",
        "operationId": "getProfile",
        "security": [{ "oauth2": ["profile:read"] }],
        "responses": {
          "200": {
            "description": "Closed account profile",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ProfileEnvelope" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    },
    "/api/v1/driver-guidance": {
      "get": {
        "tags": ["Account"],
        "summary": "Read approved driver guidance and safe document metadata",
        "operationId": "getDriverGuidance",
        "security": [{ "oauth2": ["guidance:read"] }],
        "responses": {
          "200": {
            "description": "Guidance exists or a truthful disabled empty state",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DriverGuidanceEnvelope" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    },
    "/api/v1/driver-guidance/document": {
      "get": {
        "tags": ["Account"],
        "summary": "Download the authorised user's private driver-guidance document",
        "operationId": "downloadDriverGuidanceDocument",
        "security": [{ "oauth2": ["guidance:read"] }],
        "responses": {
          "200": {
            "description": "Private no-store document body",
            "content": {
              "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    },
    "/api/v1/exports/account.json": {
      "get": {
        "tags": ["Exports"],
        "summary": "Download a private account JSON export",
        "description": "Returns the customer-owned account export with storage keys, driver share tokens, extracted contact indexes and audit metadata omitted from the OAuth variant.",
        "operationId": "downloadAccountExport",
        "security": [{ "oauth2": ["exports:read"] }],
        "responses": {
          "200": {
            "description": "Private no-store JSON attachment",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicAccountExport" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    },
    "/api/v1/exports/fleet.xlsx": {
      "get": {
        "tags": ["Exports"],
        "summary": "Download the existing Fleetkeep fleet spreadsheet export",
        "operationId": "downloadFleetSpreadsheet",
        "security": [{ "oauth2": ["exports:read"] }],
        "responses": {
          "200": {
            "description": "Private no-store XLSX attachment",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/BillingRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServiceMisconfigured" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorisation-code flow with PKCE (S256). End-user delegates per-vehicle access to a partner client. Access tokens expire after 1 hour; refresh tokens (granted with the offline_access scope) live for 30 days.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://fleetkeep.co.uk/auth/oauth2/authorize",
            "tokenUrl": "https://fleetkeep.co.uk/auth/oauth2/token",
            "refreshUrl": "https://fleetkeep.co.uk/auth/oauth2/token",
            "scopes": {
              "vehicles:read": "Read the authorised user's vehicles and compliance dates.",
              "vehicles:write": "Add, update, delete and bulk-add vehicles on the authorised user's behalf.",
              "maintenance:read": "Read the authorised user's maintenance tasks and completed history.",
              "maintenance:write": "Create, update, complete and cancel the authorised user's maintenance tasks.",
              "operations:read": "Read the authorised user's tracking snapshots, Wex route data and operational defect records.",
              "operations:write": "Report and complete defects on the authorised user's behalf.",
              "tolls:read": "Read the authorised user's toll and clean-air account records, charges and statement previews.",
              "tolls:write": "Create toll and clean-air records and apply confirmed statement imports on the authorised user's behalf.",
              "documents:read": "List and download the authorised user's private vehicle documents.",
              "documents:write": "Create private vehicle document records and uploads on the authorised user's behalf.",
              "reminders:read": "Read reminder settings and contacts.",
              "reminders:write": "Manage reminder settings and contacts, and explicitly confirm verification sends.",
              "profile:read": "Read the authorised user's Fleetkeep account profile.",
              "guidance:read": "Read the authorised user's approved driver guidance and private guidance document.",
              "exports:read": "Download the authorised user's private account and fleet spreadsheet exports.",
              "offline_access": "Issue a refresh token so the partner can refresh access without re-prompting the user."
            }
          }
        }
      }
    },
    "parameters": {
      "VehicleId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      },
      "ContactId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      },
      "BookingId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      },
      "ResourceVersion": {
        "name": "X-Fleetkeep-Resource-Version",
        "in": "header",
        "required": true,
        "schema": { "type": "string", "maxLength": 40 }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 120,
          "pattern": "^[A-Za-z0-9._:-]+$"
        }
      },
      "ListLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
      },
      "ListOffset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }
      },
      "OptionalVehicleId": {
        "name": "vehicleId",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "format": "uuid" }
      },
      "OptionalConfirmation": {
        "name": "X-Fleetkeep-Confirmation",
        "in": "header",
        "required": false,
        "schema": { "type": "string" },
        "description": "Short-lived token returned by an initial 409 and bound to the OAuth subject, bearer-token JTI, exact action and exact resource version or request digest."
      },
      "ActionConfirmation": {
        "name": "X-Fleetkeep-Confirmation",
        "in": "header",
        "required": false,
        "schema": { "type": "string" },
        "description": "Five-minute confirmation token from the immediately preceding unconfirmed request. It is bound to the user, bearer token, exact action, event and current event version."
      },
      "FleetkeepConfirmation": {
        "name": "X-Fleetkeep-Confirmation",
        "in": "header",
        "required": false,
        "schema": { "type": "string" },
        "description": "Five-minute confirmation token returned by the initial 409 response and bound to this exact record version and bearer-token JTI."
      }
    },
    "schemas": {
      "ProfileEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["profile"],
        "properties": {
          "profile": {
            "type": "object",
            "additionalProperties": false,
            "required": ["name", "email", "createdAt", "updatedAt"],
            "properties": {
              "name": { "type": ["string", "null"], "maxLength": 120 },
              "email": { "type": "string", "format": "email", "maxLength": 320 },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "DriverGuidanceDocument": {
        "type": "object",
        "additionalProperties": false,
        "required": ["fileName", "sizeBytes", "contentType", "uploadedAt", "downloadPath"],
        "properties": {
          "fileName": { "type": ["string", "null"], "maxLength": 255 },
          "sizeBytes": { "type": ["integer", "null"], "minimum": 1, "maximum": 10485760 },
          "contentType": { "type": ["string", "null"], "maxLength": 120 },
          "uploadedAt": { "type": ["string", "null"], "format": "date-time" },
          "downloadPath": { "type": "string", "const": "/api/v1/driver-guidance/document" }
        }
      },
      "DriverGuidanceEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["guidance"],
        "properties": {
          "guidance": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "enabled",
              "breakdownInfo",
              "accidentProcedure",
              "vehicleGuidance",
              "document",
              "updatedAt"
            ],
            "properties": {
              "enabled": { "type": "boolean" },
              "breakdownInfo": { "type": "string", "maxLength": 5000 },
              "accidentProcedure": { "type": "string", "maxLength": 5000 },
              "vehicleGuidance": { "type": "string", "maxLength": 5000 },
              "document": {
                "oneOf": [
                  { "$ref": "#/components/schemas/DriverGuidanceDocument" },
                  { "type": "null" }
                ]
              },
              "updatedAt": { "type": ["string", "null"], "format": "date-time" }
            }
          }
        }
      },
      "TrackingVehicle": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "registration",
          "label",
          "make",
          "model",
          "fuelType",
          "euroStatus",
          "typeApproval",
          "revenueWeight",
          "assignedDriverName",
          "connectionName",
          "provider",
          "connectionStatus",
          "lastSyncedAt",
          "lastReceivedAt",
          "lastSyncError",
          "latitude",
          "longitude",
          "odometerMiles",
          "speedMph",
          "maxSpeedMph",
          "headingDegrees",
          "voltageVolts",
          "ignition",
          "deviceStatus",
          "landmark",
          "address",
          "providerDriverName",
          "recordedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "registration": { "type": "string", "maxLength": 16 },
          "label": { "type": ["string", "null"], "maxLength": 200 },
          "make": { "type": ["string", "null"], "maxLength": 120 },
          "model": { "type": ["string", "null"], "maxLength": 120 },
          "fuelType": { "type": ["string", "null"], "maxLength": 80 },
          "euroStatus": { "type": ["string", "null"], "maxLength": 80 },
          "typeApproval": { "type": ["string", "null"], "maxLength": 80 },
          "revenueWeight": { "type": ["integer", "null"] },
          "assignedDriverName": { "type": ["string", "null"], "maxLength": 200 },
          "connectionName": { "type": ["string", "null"], "maxLength": 200 },
          "provider": { "type": ["string", "null"], "maxLength": 80 },
          "connectionStatus": { "type": ["string", "null"], "maxLength": 80 },
          "lastSyncedAt": { "type": ["string", "null"], "format": "date-time" },
          "lastReceivedAt": { "type": ["string", "null"], "format": "date-time" },
          "lastSyncError": { "type": ["string", "null"], "maxLength": 500 },
          "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90 },
          "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180 },
          "odometerMiles": { "type": ["number", "null"], "minimum": 0 },
          "speedMph": { "type": ["number", "null"], "minimum": 0 },
          "maxSpeedMph": { "type": ["number", "null"], "minimum": 0 },
          "headingDegrees": { "type": ["number", "null"], "minimum": 0, "maximum": 360 },
          "voltageVolts": { "type": ["number", "null"], "minimum": 0 },
          "ignition": { "type": ["boolean", "null"] },
          "deviceStatus": { "type": ["string", "null"], "maxLength": 500 },
          "landmark": { "type": ["string", "null"], "maxLength": 500 },
          "address": { "type": ["string", "null"], "maxLength": 500 },
          "providerDriverName": { "type": ["string", "null"], "maxLength": 200 },
          "recordedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "TrackingRoutePoint": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "recordedAt",
          "latitude",
          "longitude",
          "speedMph",
          "headingDegrees",
          "ignition",
          "odometerMiles"
        ],
        "properties": {
          "recordedAt": { "type": "string", "format": "date-time" },
          "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
          "longitude": { "type": "number", "minimum": -180, "maximum": 180 },
          "speedMph": { "type": ["number", "null"] },
          "headingDegrees": { "type": ["number", "null"] },
          "ignition": { "type": ["boolean", "null"] },
          "odometerMiles": { "type": ["number", "null"] }
        }
      },
      "TrackingTrip": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "startedAt",
          "endedAt",
          "distanceMiles",
          "durationMinutes",
          "maxSpeedMph",
          "startLatitude",
          "startLongitude",
          "endLatitude",
          "endLongitude"
        ],
        "properties": {
          "type": { "type": "string", "enum": ["trip", "idle", "stop"] },
          "startedAt": { "type": "string", "format": "date-time" },
          "endedAt": { "type": ["string", "null"], "format": "date-time" },
          "distanceMiles": { "type": ["number", "null"] },
          "durationMinutes": { "type": ["number", "null"] },
          "maxSpeedMph": { "type": ["number", "null"] },
          "startLatitude": { "type": ["number", "null"] },
          "startLongitude": { "type": ["number", "null"] },
          "endLatitude": { "type": ["number", "null"] },
          "endLongitude": { "type": ["number", "null"] }
        }
      },
      "TrackingFuelTransaction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "occurredAt",
          "transactionId",
          "volumeGallons",
          "amount",
          "pricePerGallon",
          "product",
          "siteName",
          "brandName",
          "stationAddress",
          "stationLatitude",
          "stationLongitude",
          "vehicleLatitude",
          "vehicleLongitude",
          "odometerMiles",
          "gpsDistanceMiles",
          "driverName",
          "cardName",
          "fuelLevelBefore",
          "fuelLevelAfter",
          "estimatedUkMpg"
        ],
        "properties": {
          "occurredAt": { "type": "string", "format": "date-time" },
          "transactionId": { "type": ["string", "null"], "maxLength": 160 },
          "volumeGallons": { "type": ["number", "null"] },
          "amount": { "type": ["number", "null"] },
          "pricePerGallon": { "type": ["number", "null"] },
          "product": { "type": ["string", "null"], "maxLength": 200 },
          "siteName": { "type": ["string", "null"], "maxLength": 200 },
          "brandName": { "type": ["string", "null"], "maxLength": 200 },
          "stationAddress": { "type": ["string", "null"], "maxLength": 500 },
          "stationLatitude": { "type": ["number", "null"] },
          "stationLongitude": { "type": ["number", "null"] },
          "vehicleLatitude": { "type": ["number", "null"] },
          "vehicleLongitude": { "type": ["number", "null"] },
          "odometerMiles": { "type": ["number", "null"] },
          "gpsDistanceMiles": { "type": ["number", "null"] },
          "driverName": { "type": ["string", "null"], "maxLength": 200 },
          "cardName": { "type": ["string", "null"], "maxLength": 200 },
          "fuelLevelBefore": { "type": ["number", "null"] },
          "fuelLevelAfter": { "type": ["number", "null"] },
          "estimatedUkMpg": { "type": ["number", "null"] }
        }
      },
      "TrackingRoute": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "points",
          "trips",
          "fuelTransactions",
          "diagnosticCodes",
          "provider",
          "period",
          "truncated"
        ],
        "properties": {
          "points": {
            "type": "array",
            "maxItems": 10000,
            "items": { "$ref": "#/components/schemas/TrackingRoutePoint" }
          },
          "trips": {
            "type": "array",
            "maxItems": 1000,
            "items": { "$ref": "#/components/schemas/TrackingTrip" }
          },
          "fuelTransactions": {
            "oneOf": [
              {
                "type": "array",
                "maxItems": 2000,
                "items": { "$ref": "#/components/schemas/TrackingFuelTransaction" }
              },
              { "type": "null" }
            ]
          },
          "diagnosticCodes": {
            "oneOf": [
              {
                "type": "array",
                "maxItems": 500,
                "items": { "type": "string", "maxLength": 64 }
              },
              { "type": "null" }
            ]
          },
          "provider": { "type": "string", "const": "wex" },
          "period": { "type": "string", "enum": ["today", "yesterday", "7d"] },
          "truncated": {
            "type": "object",
            "additionalProperties": false,
            "required": ["points", "trips", "fuelTransactions", "diagnosticCodes"],
            "properties": {
              "points": { "type": "boolean" },
              "trips": { "type": "boolean" },
              "fuelTransactions": { "type": "boolean" },
              "diagnosticCodes": { "type": "boolean" }
            }
          }
        }
      },
      "PublicAccountExport": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "exportedAt",
          "schemaVersion",
          "user",
          "vehicles",
          "compliance",
          "motHistory",
          "consents",
          "remindersSent",
          "driverGuidance",
          "vehicleDocuments",
          "maintenanceEventMedia",
          "vehicleConditionChecks",
          "vehicleConditionCheckMedia",
          "vehicleChargeAccounts",
          "vehicleCustomChecks",
          "vehicleChargeTransactions",
          "telematicsConnections",
          "vehicleTelematicsLinks",
          "vehicleTelematicsSnapshots"
        ],
        "properties": {
          "exportedAt": { "type": "string", "format": "date-time" },
          "schemaVersion": { "type": "string", "const": "v1-public" },
          "user": {
            "type": ["object", "null"],
            "additionalProperties": false,
            "required": ["email", "name", "createdAt", "updatedAt"],
            "properties": {
              "email": { "type": "string", "format": "email", "maxLength": 320 },
              "name": { "type": ["string", "null"] },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          },
          "vehicles": { "type": "array", "items": { "type": "object" } },
          "compliance": { "type": "array", "items": { "type": "object" } },
          "motHistory": { "type": "array", "items": { "type": "object" } },
          "consents": { "type": "array", "items": { "type": "object" } },
          "remindersSent": { "type": "array", "items": { "type": "object" } },
          "driverGuidance": { "type": "array", "items": { "type": "object" } },
          "vehicleDocuments": { "type": "array", "items": { "type": "object" } },
          "maintenanceEventMedia": { "type": "array", "items": { "type": "object" } },
          "vehicleConditionChecks": { "type": "array", "items": { "type": "object" } },
          "vehicleConditionCheckMedia": { "type": "array", "items": { "type": "object" } },
          "vehicleChargeAccounts": { "type": "array", "items": { "type": "object" } },
          "vehicleCustomChecks": { "type": "array", "items": { "type": "object" } },
          "vehicleChargeTransactions": { "type": "array", "items": { "type": "object" } },
          "telematicsConnections": { "type": "array", "items": { "type": "object" } },
          "vehicleTelematicsLinks": { "type": "array", "items": { "type": "object" } },
          "vehicleTelematicsSnapshots": { "type": "array", "items": { "type": "object" } }
        }
      },
      "ReminderSettings": {
        "type": "object",
        "additionalProperties": false,
        "required": ["enabled", "intervals"],
        "properties": {
          "enabled": { "type": "boolean" },
          "intervals": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "uniqueItems": true,
            "items": { "type": "integer", "minimum": 1, "maximum": 365 }
          }
        }
      },
      "ReminderSettingsWrite": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "enabled": { "type": "boolean" },
          "intervals": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "uniqueItems": true,
            "items": { "type": "integer", "minimum": 1, "maximum": 365 }
          }
        }
      },
      "Contact": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "email",
          "verificationStatus",
          "selectedVehicleCount",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": ["string", "null"], "maxLength": 160 },
          "email": { "type": "string", "format": "email", "maxLength": 254 },
          "verificationStatus": {
            "type": "string",
            "enum": ["pending", "verified", "unsubscribed"]
          },
          "selectedVehicleCount": { "type": "integer", "minimum": 0, "maximum": 50 },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "ContactWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email", "maxLength": 254 },
          "name": { "type": "string", "maxLength": 160 }
        }
      },
      "VehicleReminderRecipients": {
        "type": "object",
        "additionalProperties": false,
        "required": ["primaryEmail", "contacts"],
        "properties": {
          "primaryEmail": { "type": "string", "format": "email" },
          "contacts": {
            "type": "array",
            "maxItems": 5,
            "items": { "$ref": "#/components/schemas/VehicleReminderContact" }
          }
        }
      },
      "VehicleReminderContact": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "email",
          "name",
          "verifiedAt",
          "unsubscribedAt",
          "unsubscribeReason",
          "selected"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "name": { "type": ["string", "null"], "maxLength": 160 },
          "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
          "unsubscribedAt": { "type": ["string", "null"], "format": "date-time" },
          "unsubscribeReason": { "type": ["string", "null"], "maxLength": 500 },
          "selected": { "type": "boolean" }
        }
      },
      "ReminderIntervals": {
        "type": "object",
        "additionalProperties": false,
        "required": ["intervals"],
        "properties": {
          "intervals": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "uniqueItems": true,
            "items": { "type": "integer", "minimum": 1, "maximum": 365 }
          }
        }
      },
      "ReminderIntervalsWrite": {
        "$ref": "#/components/schemas/ReminderIntervals"
      },
      "VehicleReminderSettings": {
        "type": "object",
        "additionalProperties": false,
        "required": ["intervals", "primaryEmail", "contacts"],
        "properties": {
          "intervals": { "$ref": "#/components/schemas/ReminderIntervals/properties/intervals" },
          "primaryEmail": { "type": "string", "format": "email" },
          "contacts": {
            "type": "array",
            "maxItems": 5,
            "items": { "$ref": "#/components/schemas/VehicleReminderContact" }
          }
        }
      },
      "VehicleReminderMobileResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["primaryEmail", "contacts", "confirmationSent"],
        "properties": {
          "primaryEmail": { "type": "string", "format": "email" },
          "contacts": {
            "type": "array",
            "maxItems": 5,
            "items": { "$ref": "#/components/schemas/VehicleReminderContact" }
          },
          "confirmationSent": { "type": "boolean" }
        }
      },
      "VehicleReminderRecipientsWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contactIds"],
        "properties": {
          "contactIds": {
            "type": "array",
            "maxItems": 5,
            "uniqueItems": true,
            "items": { "type": "string", "format": "uuid" }
          }
        }
      },
      "ContactList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contacts"],
        "properties": {
          "contacts": {
            "type": "array",
            "maxItems": 5,
            "items": { "$ref": "#/components/schemas/Contact" }
          }
        }
      },
      "ContactEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contact"],
        "properties": {
          "contact": { "$ref": "#/components/schemas/Contact" },
          "replay": { "type": "boolean" }
        }
      },
      "OutboundPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action",
          "recipient",
          "subject",
          "text",
          "digest",
          "confirmationToken",
          "expiresAt"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["contact.verification.send", "booking.garage_email.send"]
          },
          "contactId": { "type": "string", "format": "uuid" },
          "bookingId": { "type": "string", "format": "uuid" },
          "recipient": { "type": "string", "format": "email" },
          "subject": { "type": "string", "maxLength": 240 },
          "text": { "type": "string", "maxLength": 10000 },
          "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "confirmationToken": { "type": "string" },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "OutboundResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "replay"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "replay": { "type": "boolean" }
        }
      },
      "Booking": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "maintenanceEventId",
          "vehicleId",
          "productCategory",
          "taskType",
          "taskTitle",
          "preferredPostcode",
          "preferredDate",
          "preferredGarage",
          "garageEmail",
          "garagePhone",
          "garageWebsite",
          "notes",
          "status",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "maintenanceEventId": { "type": ["string", "null"], "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "productCategory": { "type": "string", "maxLength": 32 },
          "taskType": { "type": "string", "maxLength": 80 },
          "taskTitle": { "type": "string", "maxLength": 160 },
          "preferredPostcode": { "type": "string", "maxLength": 80 },
          "preferredDate": { "type": ["string", "null"], "format": "date" },
          "preferredGarage": { "type": ["string", "null"], "maxLength": 160 },
          "garageEmail": { "type": ["string", "null"], "format": "email" },
          "garagePhone": { "type": ["string", "null"], "maxLength": 80 },
          "garageWebsite": { "type": ["string", "null"], "maxLength": 300 },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "status": { "type": "string", "maxLength": 32 },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "BookingList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["bookings"],
        "properties": {
          "bookings": {
            "type": "array",
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/Booking" }
          }
        }
      },
      "BookingWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["maintenanceEventId", "preferredPostcode"],
        "properties": {
          "maintenanceEventId": { "type": "string", "format": "uuid" },
          "preferredPostcode": { "type": "string", "minLength": 1, "maxLength": 80 },
          "preferredDate": { "type": ["string", "null"], "format": "date" },
          "preferredGarage": { "type": ["string", "null"], "maxLength": 160 },
          "garageEmail": { "type": ["string", "null"], "format": "email" },
          "garagePhone": { "type": ["string", "null"], "maxLength": 80 },
          "garageWebsite": { "type": ["string", "null"], "format": "uri" },
          "notes": { "type": ["string", "null"], "maxLength": 1200 }
        }
      },
      "BookingEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["booking"],
        "properties": {
          "booking": { "$ref": "#/components/schemas/Booking" },
          "replay": { "type": "boolean" }
        }
      },
      "BookingStatusWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["status", "expectedUpdatedAt"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["customer_contacted", "booked", "completed", "cancelled"]
          },
          "expectedUpdatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "BookingStatusEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["booking"],
        "properties": {
          "booking": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "status", "updatedAt"],
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "status": { "type": "string" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "WalkaroundSubmission": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "submissionId",
          "driverName",
          "odometerMileage",
          "safeToDrive",
          "defectNotes",
          "items"
        ],
        "properties": {
          "submissionId": { "type": "string", "format": "uuid" },
          "driverName": { "type": "string", "minLength": 2, "maxLength": 120 },
          "odometerMileage": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 1500000
          },
          "safeToDrive": { "type": "boolean" },
          "defectNotes": { "type": ["string", "null"], "maxLength": 1200 },
          "items": {
            "type": "array",
            "minItems": 9,
            "maxItems": 9,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["id", "state"],
              "properties": {
                "id": {
                  "type": "string",
                  "enum": [
                    "mirrors_glass",
                    "controls_warnings",
                    "steering_brakes_horn",
                    "seats_belts",
                    "lights_indicators",
                    "fluids_leaks",
                    "tyres_wheels",
                    "body_doors_plates",
                    "load_tow_equipment"
                  ]
                },
                "state": { "type": "string", "enum": ["ok", "defect", "not_applicable"] }
              }
            }
          }
        }
      },
      "WalkaroundDefinition": {
        "type": "object",
        "additionalProperties": false,
        "required": ["version", "groups"],
        "properties": {
          "version": { "type": "string", "const": "walkaround-v1" },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["id", "label", "items"],
              "properties": {
                "id": { "type": "string" },
                "label": { "type": "string" },
                "items": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["id", "label"],
                    "properties": { "id": { "type": "string" }, "label": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      },
      "WalkaroundSubmissionResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "checkId", "defectEventId", "mediaCount", "duplicate"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "checkId": { "type": "string", "format": "uuid" },
          "defectEventId": { "type": ["string", "null"], "format": "uuid" },
          "mediaCount": { "type": "integer", "minimum": 0, "maximum": 5 },
          "duplicate": { "type": "boolean" }
        }
      },
      "WalkaroundHistory": {
        "type": "object",
        "additionalProperties": false,
        "required": ["completedToday", "checks", "page"],
        "properties": {
          "completedToday": { "type": "boolean" },
          "checks": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "checkedAt",
                "driverName",
                "odometerMileage",
                "definitionVersion",
                "results",
                "safeToDrive",
                "defectEventId",
                "defectStatus",
                "media"
              ],
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "checkedAt": { "type": "string", "format": "date-time" },
                "driverName": { "type": ["string", "null"] },
                "odometerMileage": {
                  "type": ["integer", "null"],
                  "minimum": 0,
                  "maximum": 1500000
                },
                "definitionVersion": { "type": ["string", "null"] },
                "results": {
                  "type": ["array", "null"],
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["id", "state"],
                    "properties": {
                      "id": { "type": "string" },
                      "state": { "type": "string", "enum": ["ok", "defect", "not_applicable"] }
                    }
                  }
                },
                "safeToDrive": { "type": ["boolean", "null"] },
                "defectEventId": { "type": ["string", "null"], "format": "uuid" },
                "defectStatus": { "type": ["string", "null"] },
                "media": {
                  "type": "array",
                  "maxItems": 5,
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["id", "fileName", "contentType", "href"],
                    "properties": {
                      "id": { "type": "string", "format": "uuid" },
                      "fileName": { "type": "string" },
                      "contentType": { "type": "string" },
                      "href": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "page": {
            "type": "object",
            "additionalProperties": false,
            "required": ["limit", "offset", "hasMore", "nextOffset"],
            "properties": {
              "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
              "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740990 },
              "hasMore": { "type": "boolean" },
              "nextOffset": {
                "type": ["integer", "null"],
                "minimum": 0,
                "maximum": 9007199254740991
              }
            }
          }
        }
      },
      "VehicleDocument": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "documentType",
          "title",
          "reference",
          "supplier",
          "issuedAt",
          "expiresAt",
          "notes",
          "storageStatus",
          "fileName",
          "fileSize",
          "contentType",
          "uploadedAt",
          "driverVisible",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "documentType": {
            "type": "string",
            "enum": [
              "service_record",
              "invoice",
              "insurance",
              "inspection",
              "toll_statement",
              "warranty",
              "other"
            ]
          },
          "title": { "type": "string" },
          "reference": { "type": ["string", "null"] },
          "supplier": { "type": ["string", "null"] },
          "issuedAt": { "type": ["string", "null"], "format": "date" },
          "expiresAt": { "type": ["string", "null"], "format": "date" },
          "notes": { "type": ["string", "null"] },
          "storageStatus": { "type": "string", "enum": ["metadata_only", "uploaded"] },
          "fileName": { "type": ["string", "null"] },
          "fileSize": { "type": ["integer", "null"], "minimum": 0, "maximum": 10485760 },
          "contentType": { "type": ["string", "null"] },
          "uploadedAt": { "type": ["string", "null"], "format": "date-time" },
          "driverVisible": { "type": "boolean" },
          "createdAt": { "type": "string", "format": "date-time" },
          "downloadHref": { "type": ["string", "null"] }
        }
      },
      "VehicleDocumentList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["records", "page"],
        "properties": {
          "records": {
            "type": "array",
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/VehicleDocument" }
          },
          "page": {
            "type": "object",
            "additionalProperties": false,
            "required": ["limit", "offset", "hasMore", "nextOffset"],
            "properties": {
              "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
              "offset": { "type": "integer", "minimum": 0 },
              "hasMore": { "type": "boolean" },
              "nextOffset": { "type": ["integer", "null"], "minimum": 0 }
            }
          }
        }
      },
      "VehicleDocumentInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["documentType", "title"],
        "properties": {
          "documentType": {
            "type": "string",
            "enum": [
              "service_record",
              "invoice",
              "insurance",
              "inspection",
              "toll_statement",
              "warranty",
              "other"
            ]
          },
          "title": { "type": "string", "minLength": 1, "maxLength": 160 },
          "reference": { "type": ["string", "null"], "maxLength": 160 },
          "supplier": { "type": ["string", "null"], "maxLength": 160 },
          "issuedAt": { "type": ["string", "null"], "format": "date" },
          "expiresAt": { "type": ["string", "null"], "format": "date" },
          "notes": { "type": ["string", "null"], "maxLength": 1200 }
        }
      },
      "VehiclePhoto": {
        "type": "object",
        "additionalProperties": false,
        "required": ["href", "fileName", "fileSize", "contentType", "uploadedAt"],
        "properties": {
          "href": { "type": "string" },
          "fileName": { "type": "string" },
          "fileSize": { "type": "integer", "minimum": 1, "maximum": 10485760 },
          "contentType": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"] },
          "uploadedAt": { "type": "string", "format": "date-time" }
        }
      },
      "VehiclePhotoRemoval": {
        "type": "object",
        "additionalProperties": false,
        "required": ["removed"],
        "properties": { "removed": { "type": "boolean" } }
      },
      "MaintenanceInput": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "oil_change",
              "brake_check",
              "tyre_check",
              "service",
              "inspection",
              "document_renewal",
              "repair",
              "other"
            ]
          },
          "title": { "type": ["string", "null"], "maxLength": 120 },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "dueDate": { "type": ["string", "null"], "format": "date" },
          "dueMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 2000000 },
          "recurrenceIntervalDays": {
            "type": ["integer", "null"],
            "minimum": 1,
            "maximum": 365,
            "description": "Requires dueDate. Completion creates a successor due this many days later."
          },
          "supplier": { "type": ["string", "null"], "maxLength": 160 },
          "priority": { "type": ["string", "null"], "enum": ["low", "normal", "high", null] }
        },
        "additionalProperties": false
      },
      "ForecastMaintenanceInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "forecast", "forecastConsent"],
        "description": "Opt in using a confirmed last check and expected annual mileage. Dates are calculated; reminders use the account's existing email consent. One open forecast per vehicle and check type. Duplicate setup returns 409; refresh instead of creating another type to bypass it.",
        "properties": {
          "type": { "$ref": "#/components/schemas/MaintenanceInput/properties/type" },
          "title": { "type": "string", "maxLength": 110 },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "forecastConsent": { "const": true },
          "forecast": {
            "allOf": [
              { "$ref": "#/components/schemas/MaintenanceEvent/properties/forecast" },
              { "type": "object" }
            ]
          }
        }
      },
      "MaintenanceEvent": {
        "type": "object",
        "required": ["id", "vehicleId", "type", "title", "status", "priority", "createdAt"],
        "properties": {
          "forecast": {
            "type": ["object", "null"],
            "required": [
              "baselineDate",
              "baselineMileage",
              "intervalMiles",
              "annualMileage",
              "reminderDays"
            ],
            "properties": {
              "baselineDate": { "type": "string", "format": "date" },
              "baselineMileage": { "type": "integer", "minimum": 0 },
              "intervalMiles": { "type": "integer", "minimum": 1 },
              "annualMileage": { "type": "number", "exclusiveMinimum": 0 },
              "reminderDays": {
                "type": "array",
                "minItems": 1,
                "maxItems": 8,
                "items": { "type": "integer", "minimum": 0, "maximum": 365 }
              }
            }
          },
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "registration": { "type": "string" },
          "vehicleLabel": { "type": ["string", "null"] },
          "type": {
            "type": "string",
            "enum": [
              "oil_change",
              "brake_check",
              "tyre_check",
              "service",
              "inspection",
              "document_renewal",
              "repair",
              "other"
            ]
          },
          "title": { "type": "string" },
          "notes": { "type": ["string", "null"] },
          "dueDate": { "type": ["string", "null"], "format": "date" },
          "dueMileage": { "type": ["integer", "null"] },
          "recurrenceIntervalDays": { "type": ["integer", "null"] },
          "supplier": { "type": ["string", "null"] },
          "priority": { "type": "string", "enum": ["low", "normal", "high"] },
          "status": { "type": "string", "enum": ["open", "completed"] },
          "completedAt": { "type": ["string", "null"], "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" },
          "dueStatus": { "$ref": "#/components/schemas/MaintenanceDueStatus" }
        },
        "additionalProperties": false
      },
      "MaintenanceDueStatus": {
        "type": "object",
        "required": ["level", "reason", "daysUntil", "milesUntil"],
        "properties": {
          "level": {
            "type": "string",
            "enum": ["overdue", "critical", "warning", "clear", "unknown"]
          },
          "reason": { "type": "string", "enum": ["date", "mileage", "none"] },
          "daysUntil": { "type": ["integer", "null"] },
          "milesUntil": { "type": ["integer", "null"] }
        },
        "additionalProperties": false
      },
      "MaintenanceList": {
        "type": "object",
        "required": ["open", "recent"],
        "properties": {
          "open": { "type": "array", "items": { "$ref": "#/components/schemas/MaintenanceEvent" } },
          "recent": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/MaintenanceEvent" }
          }
        },
        "additionalProperties": false
      },
      "MaintenanceCompletion": {
        "type": "object",
        "required": ["ok", "completed", "eventId", "successorId"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "completed": { "type": "boolean", "const": true },
          "eventId": { "type": "string", "format": "uuid" },
          "successorId": { "type": ["string", "null"], "format": "uuid" }
        },
        "additionalProperties": false
      },
      "DefectInput": {
        "type": "object",
        "required": ["vehicleId", "title", "notes", "priority", "reportedBy", "followUpAction"],
        "properties": {
          "vehicleId": { "type": "string", "format": "uuid" },
          "title": { "type": "string", "minLength": 1, "maxLength": 120 },
          "notes": { "type": "string", "minLength": 1, "maxLength": 1200 },
          "priority": { "type": "string", "enum": ["low", "normal", "high", "safety_critical"] },
          "reportedBy": { "type": "string", "minLength": 1, "maxLength": 120 },
          "followUpAction": { "type": "string", "minLength": 1, "maxLength": 1200 }
        },
        "additionalProperties": false
      },
      "DefectEvent": {
        "type": "object",
        "required": [
          "id",
          "vehicleId",
          "registration",
          "vehicleLabel",
          "title",
          "notes",
          "priority",
          "reportedBy",
          "followUpAction",
          "status",
          "completedAt",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "registration": { "type": "string" },
          "vehicleLabel": { "type": ["string", "null"] },
          "title": { "type": "string" },
          "notes": { "type": ["string", "null"] },
          "priority": { "type": "string", "enum": ["low", "normal", "high", "safety_critical"] },
          "reportedBy": { "type": ["string", "null"] },
          "followUpAction": { "type": ["string", "null"] },
          "status": { "type": "string", "enum": ["open", "completed"] },
          "completedAt": { "type": ["string", "null"], "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "DefectList": {
        "type": "object",
        "required": ["open", "recent"],
        "properties": {
          "open": { "type": "array", "items": { "$ref": "#/components/schemas/DefectEvent" } },
          "recent": { "type": "array", "items": { "$ref": "#/components/schemas/DefectEvent" } }
        },
        "additionalProperties": false
      },
      "DefectCompletion": {
        "type": "object",
        "required": ["ok", "completed", "eventId", "vehicleId"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "completed": { "type": "boolean", "const": true },
          "eventId": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" }
        },
        "additionalProperties": false
      },
      "EquipmentDetail": {
        "type": "object",
        "required": ["label", "value"],
        "properties": {
          "label": { "type": "string", "maxLength": 60 },
          "value": { "type": "string", "maxLength": 240 }
        },
        "additionalProperties": false
      },
      "EquipmentInput": {
        "type": "object",
        "required": ["name", "category", "status"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 120 },
          "presetKey": {
            "type": ["string", "null"],
            "enum": [
              "tunnel_account",
              "bridge_crossing",
              "gps_tracker",
              "ghost_immobiliser",
              "fuel_card",
              "breakdown_cover",
              "warranty",
              "ownership_hire",
              "service_due",
              null
            ]
          },
          "category": { "type": "string", "enum": ["tracking", "security", "fuel", "other"] },
          "status": {
            "type": "string",
            "enum": ["in_place", "needs_attention", "not_applicable", "removed"]
          },
          "provider": { "type": ["string", "null"], "maxLength": 120 },
          "reference": { "type": ["string", "null"], "maxLength": 160 },
          "portalUrl": { "type": ["string", "null"], "format": "uri", "maxLength": 500 },
          "startedOn": { "type": ["string", "null"], "format": "date" },
          "endedOn": { "type": ["string", "null"], "format": "date" },
          "reviewDueDate": { "type": ["string", "null"], "format": "date" },
          "reminderEnabled": { "type": "boolean" },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "details": {
            "type": ["array", "null"],
            "maxItems": 8,
            "items": { "$ref": "#/components/schemas/EquipmentDetail" }
          }
        },
        "additionalProperties": false
      },
      "EquipmentUpdateInput": {
        "type": "object",
        "required": ["id", "name", "category", "status"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "$ref": "#/components/schemas/EquipmentInput/properties/name" },
          "presetKey": { "$ref": "#/components/schemas/EquipmentInput/properties/presetKey" },
          "category": { "$ref": "#/components/schemas/EquipmentInput/properties/category" },
          "status": { "$ref": "#/components/schemas/EquipmentInput/properties/status" },
          "provider": { "$ref": "#/components/schemas/EquipmentInput/properties/provider" },
          "reference": { "$ref": "#/components/schemas/EquipmentInput/properties/reference" },
          "portalUrl": { "$ref": "#/components/schemas/EquipmentInput/properties/portalUrl" },
          "startedOn": { "$ref": "#/components/schemas/EquipmentInput/properties/startedOn" },
          "endedOn": { "$ref": "#/components/schemas/EquipmentInput/properties/endedOn" },
          "reviewDueDate": {
            "$ref": "#/components/schemas/EquipmentInput/properties/reviewDueDate"
          },
          "reminderEnabled": {
            "$ref": "#/components/schemas/EquipmentInput/properties/reminderEnabled"
          },
          "notes": { "$ref": "#/components/schemas/EquipmentInput/properties/notes" },
          "details": { "$ref": "#/components/schemas/EquipmentInput/properties/details" }
        },
        "additionalProperties": false
      },
      "EquipmentRecord": {
        "allOf": [
          { "$ref": "#/components/schemas/EquipmentInput" },
          {
            "type": "object",
            "required": ["id", "active", "createdAt", "updatedAt"],
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "active": { "type": "boolean" },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "EquipmentRemovalResult": {
        "type": "object",
        "required": ["ok", "equipment"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "equipment": {
            "type": "object",
            "required": ["id", "status", "active"],
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "status": { "type": "string", "const": "removed" },
              "active": { "type": "boolean", "const": false }
            }
          }
        }
      },
      "EquipmentPreset": {
        "type": "object",
        "required": ["key", "name", "shortLabel", "category", "description"],
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "tunnel_account",
              "bridge_crossing",
              "gps_tracker",
              "ghost_immobiliser",
              "fuel_card"
            ]
          },
          "name": { "type": "string" },
          "shortLabel": { "type": "string" },
          "category": { "type": "string", "enum": ["tracking", "security", "fuel", "other"] },
          "description": { "type": "string" }
        }
      },
      "EquipmentTemplateInput": {
        "type": "object",
        "required": ["vehicleIds", "presetKeys"],
        "properties": {
          "vehicleIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": { "type": "string", "format": "uuid" }
          },
          "presetKeys": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "tunnel_account",
                "bridge_crossing",
                "gps_tracker",
                "ghost_immobiliser",
                "fuel_card"
              ]
            }
          },
          "startedOn": { "type": ["string", "null"], "format": "date" },
          "reviewDueDate": { "type": ["string", "null"], "format": "date" },
          "confirmDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
        },
        "additionalProperties": false
      },
      "EquipmentTemplateApplyInput": {
        "allOf": [
          { "$ref": "#/components/schemas/EquipmentTemplateInput" },
          {
            "type": "object",
            "required": ["confirmDigest"],
            "properties": {
              "confirmDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
            }
          }
        ]
      },
      "EquipmentTemplateResult": {
        "type": "object",
        "required": ["digest", "requested", "added", "skippedAlreadyActive"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "confirmationRequired": { "type": "boolean", "const": true },
          "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "requested": { "type": "integer", "minimum": 1, "maximum": 500 },
          "added": { "type": "integer", "minimum": 0, "maximum": 500 },
          "skippedAlreadyActive": { "type": "integer", "minimum": 0, "maximum": 500 }
        }
      },
      "ServiceRecordInput": {
        "type": "object",
        "required": ["servicedAt", "workSummary"],
        "properties": {
          "servicedAt": { "type": "string", "format": "date" },
          "odometerMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 9999999 },
          "supplier": { "type": ["string", "null"], "maxLength": 160 },
          "invoiceReference": { "type": ["string", "null"], "maxLength": 160 },
          "costPence": { "type": ["integer", "null"], "minimum": 0, "maximum": 10000000 },
          "workSummary": { "type": "string", "minLength": 1, "maxLength": 1200 },
          "partsNotes": { "type": ["string", "null"], "maxLength": 1200 },
          "nextServiceDueDate": { "type": ["string", "null"], "format": "date" },
          "nextServiceDueMileage": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 9999999
          },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "updateServiceReminder": { "type": "boolean", "default": true }
        },
        "additionalProperties": false
      },
      "ServiceRecord": {
        "type": "object",
        "required": [
          "id",
          "vehicleId",
          "servicedAt",
          "odometerMileage",
          "supplier",
          "invoiceReference",
          "costPence",
          "workSummary",
          "partsNotes",
          "nextServiceDueDate",
          "nextServiceDueMileage",
          "notes",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "servicedAt": { "type": "string", "format": "date" },
          "odometerMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 9999999 },
          "supplier": { "type": ["string", "null"], "maxLength": 160 },
          "invoiceReference": { "type": ["string", "null"], "maxLength": 160 },
          "costPence": { "type": ["integer", "null"], "minimum": 0, "maximum": 10000000 },
          "workSummary": { "type": "string", "maxLength": 1200 },
          "partsNotes": { "type": ["string", "null"], "maxLength": 1200 },
          "nextServiceDueDate": { "type": ["string", "null"], "format": "date" },
          "nextServiceDueMileage": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 9999999
          },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "ServiceRecordCreateEnvelope": {
        "type": "object",
        "required": ["record", "replay"],
        "properties": {
          "record": { "$ref": "#/components/schemas/ServiceRecord" },
          "replay": { "type": "boolean" }
        },
        "additionalProperties": false
      },
      "ServiceSchedule": {
        "type": "object",
        "required": [
          "id",
          "vehicleId",
          "sourceKind",
          "providerName",
          "providerScheduleId",
          "market",
          "modelYear",
          "variant",
          "scheduleVersion",
          "matchStatus",
          "intervalMonths",
          "intervalDays",
          "intervalMiles",
          "sourceUpdatedAt",
          "retrievedAt",
          "isCurrent",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "sourceKind": { "type": "string", "enum": ["provider", "operator"] },
          "providerName": { "type": ["string", "null"], "maxLength": 120 },
          "providerScheduleId": { "type": ["string", "null"], "maxLength": 160 },
          "market": { "type": ["string", "null"], "maxLength": 80 },
          "modelYear": { "type": ["integer", "null"], "minimum": 1, "maximum": 3000 },
          "variant": { "type": ["string", "null"], "maxLength": 240 },
          "scheduleVersion": { "type": ["string", "null"], "maxLength": 120 },
          "matchStatus": {
            "type": "string",
            "enum": ["matched", "needs_review", "unsupported"]
          },
          "intervalMonths": { "type": ["integer", "null"], "minimum": 1, "maximum": 240 },
          "intervalDays": { "type": ["integer", "null"], "minimum": 1, "maximum": 7300 },
          "intervalMiles": {
            "type": ["integer", "null"],
            "minimum": 1,
            "maximum": 2000000
          },
          "sourceUpdatedAt": { "type": ["string", "null"], "format": "date-time" },
          "retrievedAt": { "type": "string", "format": "date-time" },
          "isCurrent": { "type": "boolean" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "ServiceEvidenceRequest": {
        "type": "object",
        "required": [
          "id",
          "vehicleId",
          "scheduleId",
          "recipientName",
          "recipientEmail",
          "status",
          "deliveryStatus",
          "requestedAt",
          "dueAt",
          "lastContactedAt",
          "nextFollowUpAt",
          "followUpCount",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "scheduleId": { "type": ["string", "null"], "format": "uuid" },
          "recipientName": { "type": ["string", "null"], "maxLength": 160 },
          "recipientEmail": { "type": "string", "format": "email", "maxLength": 254 },
          "status": {
            "type": "string",
            "enum": [
              "prepared",
              "awaiting_evidence",
              "evidence_received",
              "under_review",
              "accepted",
              "rejected",
              "closed"
            ]
          },
          "deliveryStatus": {
            "type": "string",
            "enum": ["not_sent", "sent", "delivered", "failed"]
          },
          "requestedAt": { "type": ["string", "null"], "format": "date-time" },
          "dueAt": { "type": ["string", "null"], "format": "date-time" },
          "lastContactedAt": { "type": ["string", "null"], "format": "date-time" },
          "nextFollowUpAt": { "type": ["string", "null"], "format": "date-time" },
          "followUpCount": { "type": "integer", "minimum": 0 },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "ServiceEvidenceContact": {
        "type": "object",
        "required": [
          "id",
          "vehicleId",
          "requestId",
          "channel",
          "outcome",
          "detail",
          "contactedAt",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "requestId": { "type": "string", "format": "uuid" },
          "channel": { "type": "string", "enum": ["email", "phone", "sms", "portal", "other"] },
          "outcome": {
            "type": "string",
            "enum": ["sent", "delivered", "failed", "no_response", "replied"]
          },
          "detail": { "type": ["string", "null"], "maxLength": 1000 },
          "contactedAt": { "type": "string", "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "ServiceEvidenceSubmission": {
        "type": "object",
        "required": [
          "id",
          "vehicleId",
          "requestId",
          "submittedByName",
          "submittedByEmail",
          "serviceDate",
          "odometerMileage",
          "statement",
          "documentIds",
          "reviewStatus",
          "reviewReason",
          "reviewedAt",
          "submittedAt",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "requestId": { "type": "string", "format": "uuid" },
          "submittedByName": { "type": ["string", "null"], "maxLength": 160 },
          "submittedByEmail": { "type": ["string", "null"], "format": "email" },
          "serviceDate": { "type": ["string", "null"], "format": "date" },
          "odometerMileage": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 2000000
          },
          "statement": { "type": ["string", "null"], "maxLength": 2000 },
          "documentIds": {
            "type": "array",
            "maxItems": 10,
            "items": { "type": "string", "format": "uuid" }
          },
          "reviewStatus": {
            "type": "string",
            "enum": ["pending", "accepted", "rejected", "clarification_requested"]
          },
          "reviewReason": { "type": ["string", "null"], "maxLength": 1200 },
          "reviewedAt": { "type": ["string", "null"], "format": "date-time" },
          "submittedAt": { "type": "string", "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "CreatedServiceRecord": {
        "type": "object",
        "required": [
          "id",
          "servicedAt",
          "odometerMileage",
          "supplier",
          "invoiceReference",
          "costPence",
          "workSummary",
          "partsNotes",
          "nextServiceDueDate",
          "nextServiceDueMileage",
          "notes",
          "updateServiceReminder",
          "createdAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "servicedAt": { "type": "string", "format": "date" },
          "odometerMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 9999999 },
          "supplier": { "type": ["string", "null"], "maxLength": 160 },
          "invoiceReference": { "type": ["string", "null"], "maxLength": 160 },
          "costPence": { "type": ["integer", "null"], "minimum": 0, "maximum": 10000000 },
          "workSummary": { "type": "string", "maxLength": 1200 },
          "partsNotes": { "type": ["string", "null"], "maxLength": 1200 },
          "nextServiceDueDate": { "type": ["string", "null"], "format": "date" },
          "nextServiceDueMileage": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 9999999
          },
          "notes": { "type": ["string", "null"], "maxLength": 1200 },
          "updateServiceReminder": { "type": "boolean" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "ActionConfirmationRequired": {
        "type": "object",
        "required": ["error", "confirmationToken", "expiresAt"],
        "properties": {
          "error": { "type": "string", "const": "confirmation_required" },
          "confirmationToken": { "type": "string" },
          "expiresAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "TollReviewWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["suggestionId", "decision"],
        "properties": {
          "suggestionId": { "type": "string", "format": "uuid" },
          "decision": { "type": "string", "enum": ["confirm", "dismiss"] }
        }
      },
      "TollReviewResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "message"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "message": { "type": "string" }
        }
      },
      "TollOperations": {
        "type": "object",
        "additionalProperties": false,
        "required": ["summary", "recent", "suggestions"],
        "properties": {
          "summary": {
            "type": "object",
            "additionalProperties": false,
            "required": ["totalPence", "count", "needsReview"],
            "properties": {
              "totalPence": { "type": "integer" },
              "count": { "type": "integer", "minimum": 0 },
              "needsReview": { "type": "integer", "minimum": 0 }
            }
          },
          "recent": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "vehicleId",
                "registration",
                "vehicleLabel",
                "providerName",
                "chargeType",
                "chargedOn",
                "amountPence",
                "currency",
                "location",
                "status"
              ],
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "vehicleId": { "type": "string", "format": "uuid" },
                "registration": { "type": "string" },
                "vehicleLabel": { "type": ["string", "null"] },
                "providerName": { "type": "string" },
                "chargeType": { "type": "string" },
                "chargedOn": { "type": "string", "format": "date" },
                "amountPence": { "type": "integer" },
                "currency": { "type": "string", "const": "GBP" },
                "location": { "type": ["string", "null"] },
                "status": { "type": "string" }
              }
            }
          },
          "suggestions": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "vehicleId",
                "registration",
                "vehicleLabel",
                "providerName",
                "locationName",
                "tollType",
                "detectedAt",
                "distanceMetres",
                "estimatedAmountPence",
                "discountedAmountPence",
                "currency",
                "confidence",
                "status",
                "officialUrl"
              ],
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "vehicleId": { "type": "string", "format": "uuid" },
                "registration": { "type": "string" },
                "vehicleLabel": { "type": ["string", "null"] },
                "providerName": { "type": "string" },
                "locationName": { "type": "string" },
                "tollType": { "type": "string" },
                "detectedAt": { "type": "string", "format": "date-time" },
                "distanceMetres": { "type": "integer", "minimum": 0 },
                "estimatedAmountPence": { "type": ["integer", "null"] },
                "discountedAmountPence": { "type": ["integer", "null"] },
                "currency": { "type": "string", "const": "GBP" },
                "confidence": { "type": "string", "const": "likely" },
                "status": {
                  "type": "string",
                  "enum": ["pending", "confirmed", "dismissed", "matched"]
                },
                "officialUrl": { "type": ["string", "null"], "format": "uri" }
              }
            }
          }
        }
      },
      "TollAccountWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["vehicleId", "providerName", "coverageArea"],
        "properties": {
          "vehicleId": { "type": "string", "format": "uuid" },
          "providerName": { "type": "string", "minLength": 1, "maxLength": 120 },
          "coverageArea": { "type": "string", "minLength": 1, "maxLength": 160 },
          "accountReference": { "type": ["string", "null"], "maxLength": 160 },
          "portalUrl": { "type": ["string", "null"], "format": "uri", "pattern": "^https://" },
          "autoPayEnabled": { "type": "boolean", "default": false },
          "paymentMethodNote": { "type": ["string", "null"], "maxLength": 160 },
          "reviewDueDate": { "type": ["string", "null"], "format": "date" },
          "status": {
            "type": "string",
            "enum": ["active", "review_needed", "not_used"],
            "default": "active"
          },
          "notes": { "type": ["string", "null"], "maxLength": 1200 }
        }
      },
      "TollAccount": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "vehicleId",
          "providerName",
          "coverageArea",
          "accountReference",
          "portalUrl",
          "autoPayEnabled",
          "paymentMethodNote",
          "reviewDueDate",
          "status",
          "notes",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "providerName": { "type": "string" },
          "coverageArea": { "type": "string" },
          "accountReference": { "type": ["string", "null"] },
          "portalUrl": { "type": ["string", "null"] },
          "autoPayEnabled": { "type": "boolean" },
          "paymentMethodNote": { "type": ["string", "null"] },
          "reviewDueDate": { "type": ["string", "null"], "format": "date" },
          "status": { "type": "string" },
          "notes": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "TollAccountEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["account", "replay"],
        "properties": {
          "account": { "$ref": "#/components/schemas/TollAccount" },
          "replay": { "type": "boolean" }
        }
      },
      "TollAccountList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["accounts", "limit", "offset"],
        "properties": {
          "accounts": {
            "type": "array",
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/TollAccount" }
          },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "TollTransactionWrite": {
        "type": "object",
        "additionalProperties": false,
        "required": ["vehicleId", "providerName", "chargedOn", "amountPence"],
        "properties": {
          "vehicleId": { "type": "string", "format": "uuid" },
          "chargeAccountId": { "type": ["string", "null"], "format": "uuid" },
          "providerName": { "type": "string", "minLength": 1, "maxLength": 120 },
          "chargeType": {
            "type": "string",
            "enum": ["toll", "congestion", "ulez", "clean_air_zone", "penalty", "adjustment"],
            "default": "toll"
          },
          "chargedOn": { "type": "string", "format": "date" },
          "amountPence": { "type": "integer", "minimum": 0, "maximum": 10000000 },
          "location": { "type": ["string", "null"], "maxLength": 160 },
          "invoiceReference": { "type": ["string", "null"], "maxLength": 160 },
          "status": {
            "type": "string",
            "enum": ["recorded", "needs_review", "disputed", "reimbursed"],
            "default": "recorded"
          },
          "notes": { "type": ["string", "null"], "maxLength": 1200 }
        }
      },
      "TollTransaction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "vehicleId",
          "chargeAccountId",
          "providerName",
          "chargeType",
          "chargedOn",
          "amountPence",
          "currency",
          "location",
          "invoiceReference",
          "source",
          "status",
          "notes",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "vehicleId": { "type": "string", "format": "uuid" },
          "chargeAccountId": { "type": ["string", "null"], "format": "uuid" },
          "providerName": { "type": "string" },
          "chargeType": { "type": "string" },
          "chargedOn": { "type": "string", "format": "date" },
          "amountPence": { "type": "integer" },
          "currency": { "type": "string", "const": "GBP" },
          "location": { "type": ["string", "null"] },
          "invoiceReference": { "type": ["string", "null"] },
          "source": { "type": "string" },
          "status": { "type": "string" },
          "notes": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "TollTransactionEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["transaction", "replay"],
        "properties": {
          "transaction": { "$ref": "#/components/schemas/TollTransaction" },
          "replay": { "type": "boolean" }
        }
      },
      "TollTransactionList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["transactions", "limit", "offset"],
        "properties": {
          "transactions": {
            "type": "array",
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/TollTransaction" }
          },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "TollImportPayload": {
        "type": "object",
        "additionalProperties": false,
        "required": ["sourceName", "csv"],
        "properties": {
          "sourceName": {
            "type": "string",
            "pattern": "\\.[cC][sS][vV]$",
            "maxLength": 160
          },
          "csv": {
            "type": "string",
            "description": "UTF-8 CSV content, limited to 262,144 bytes.",
            "x-maxBytes": 262144
          }
        }
      },
      "TollImportApplyPayload": {
        "type": "object",
        "additionalProperties": false,
        "required": ["sourceName", "csv", "confirmDigest"],
        "properties": {
          "sourceName": {
            "type": "string",
            "pattern": "\\.[cC][sS][vV]$",
            "maxLength": 160
          },
          "csv": {
            "type": "string",
            "description": "UTF-8 CSV content, limited to 262,144 bytes.",
            "x-maxBytes": 262144
          },
          "confirmDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
        }
      },
      "TollImportRow": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rowNumber",
          "registration",
          "providerName",
          "chargedOn",
          "amountPence",
          "chargeType",
          "location",
          "outcome"
        ],
        "properties": {
          "rowNumber": { "type": "integer", "minimum": 2, "maximum": 501 },
          "registration": { "type": "string" },
          "providerName": { "type": "string" },
          "chargedOn": { "type": "string", "format": "date" },
          "amountPence": { "type": "integer", "minimum": 0 },
          "chargeType": { "type": "string" },
          "location": { "type": ["string", "null"] },
          "outcome": { "type": "string", "enum": ["importable", "duplicate", "unknown_vehicle"] }
        }
      },
      "TollImportPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sourceName",
          "digest",
          "rowCount",
          "importableCount",
          "duplicateCount",
          "unknownCount",
          "detectedProviderName",
          "rows",
          "rowsTruncated",
          "confirmationRequired"
        ],
        "properties": {
          "sourceName": { "type": "string" },
          "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "rowCount": { "type": "integer", "minimum": 1, "maximum": 500 },
          "importableCount": { "type": "integer", "minimum": 0, "maximum": 500 },
          "duplicateCount": { "type": "integer", "minimum": 0, "maximum": 500 },
          "unknownCount": { "type": "integer", "minimum": 0, "maximum": 500 },
          "detectedProviderName": { "type": ["string", "null"] },
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/TollImportRow" }
          },
          "rowsTruncated": { "type": "boolean" },
          "confirmationRequired": { "type": "boolean", "const": true }
        }
      },
      "TollImportResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "batchId",
          "imported",
          "duplicates",
          "unknown",
          "detectedProviderName",
          "replay"
        ],
        "properties": {
          "batchId": { "type": "string", "format": "uuid" },
          "imported": { "type": "integer", "minimum": 0, "maximum": 500 },
          "duplicates": { "type": "integer", "minimum": 0, "maximum": 500 },
          "unknown": { "type": "integer", "minimum": 0, "maximum": 500 },
          "detectedProviderName": { "type": ["string", "null"] },
          "replay": { "type": "boolean" }
        }
      },
      "SpreadsheetPayload": {
        "oneOf": [
          {
            "type": "object",
            "required": ["sourceName", "csv"],
            "properties": {
              "sourceName": { "type": "string", "pattern": "\\.csv$", "maxLength": 160 },
              "csv": { "type": "string", "maxLength": 262144 }
            }
          },
          {
            "type": "object",
            "required": ["sourceName", "contentBase64"],
            "properties": {
              "sourceName": { "type": "string", "pattern": "\\.xlsx$", "maxLength": 160 },
              "contentBase64": { "type": "string", "contentEncoding": "base64" }
            }
          }
        ]
      },
      "ApplySpreadsheetPayload": {
        "allOf": [
          { "$ref": "#/components/schemas/SpreadsheetPayload" },
          {
            "type": "object",
            "required": ["confirmDigest", "idempotencyKey"],
            "properties": {
              "confirmDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
              "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128 }
            }
          }
        ]
      },
      "VehicleImportPreview": {
        "type": "object",
        "required": ["sourceName", "digest", "preview", "rows", "confirmationRequired"],
        "properties": {
          "sourceName": { "type": "string" },
          "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "confirmationRequired": { "type": "boolean", "const": true },
          "preview": { "type": "object" },
          "rows": { "type": "array", "items": { "type": "object" } }
        }
      },
      "VehicleImportResult": {
        "type": "object",
        "required": ["summary", "outcomes"],
        "properties": {
          "replayed": { "type": "boolean" },
          "summary": { "type": "object" },
          "outcomes": { "type": "array", "items": { "type": "object" } }
        }
      },
      "Vehicle": {
        "type": "object",
        "description": "A single vehicle on the authorised user's account. Official vehicle and compliance fields are populated from DVLA and DVSA records. Insurance, service, operational status and assigned driver fields are user-supplied. serviceDueDate is computed from lastServiceDate using serviceIntervalDays when set, otherwise serviceIntervalMonths.",
        "required": [
          "id",
          "registration",
          "label",
          "make",
          "model",
          "yearOfManufacture",
          "fuelType",
          "motDueDate",
          "taxDueDate",
          "insuranceDueDate",
          "lastServiceDate",
          "lastServiceMileage",
          "serviceIntervalMonths",
          "serviceIntervalDays",
          "serviceDueDate",
          "operationalStatus",
          "assignedDriverName",
          "assignedDriverContact",
          "statusNotes"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "registration": { "type": "string", "example": "BD15 KFG" },
          "label": { "type": ["string", "null"], "maxLength": 80, "example": "Transit white" },
          "make": { "type": ["string", "null"], "example": "FORD" },
          "model": { "type": ["string", "null"], "example": "TRANSIT CUSTOM" },
          "yearOfManufacture": { "type": ["integer", "null"], "example": 2018 },
          "fuelType": { "type": ["string", "null"], "example": "DIESEL" },
          "motDueDate": { "type": ["string", "null"], "format": "date" },
          "taxDueDate": { "type": ["string", "null"], "format": "date" },
          "insuranceDueDate": { "type": ["string", "null"], "format": "date" },
          "lastServiceDate": { "type": ["string", "null"], "format": "date" },
          "lastServiceMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 1500000 },
          "serviceIntervalMonths": { "type": ["integer", "null"], "minimum": 1, "maximum": 120 },
          "serviceIntervalDays": { "type": ["integer", "null"], "minimum": 1, "maximum": 3650 },
          "serviceDueDate": {
            "type": ["string", "null"],
            "format": "date",
            "description": "Computed from lastServiceDate using serviceIntervalDays when set, otherwise serviceIntervalMonths. Null when the date or interval is missing."
          },
          "operationalStatus": {
            "type": "string",
            "enum": ["active", "standby", "in_maintenance", "off_road", "sold_or_removed"],
            "default": "active",
            "example": "active"
          },
          "assignedDriverName": {
            "type": ["string", "null"],
            "maxLength": 120,
            "example": "Alex Driver"
          },
          "assignedDriverContact": {
            "type": ["string", "null"],
            "maxLength": 160,
            "example": "alex@example.com / 07700 900000"
          },
          "statusNotes": {
            "type": ["string", "null"],
            "maxLength": 1000,
            "example": "Keep as standby vehicle until next inspection."
          }
        }
      },
      "AddVehicleInput": {
        "type": "object",
        "required": ["registration"],
        "properties": {
          "registration": { "type": "string", "example": "BD15 KFG" },
          "label": { "type": ["string", "null"], "maxLength": 80 },
          "insuranceDueDate": { "type": ["string", "null"], "format": "date" },
          "lastServiceDate": { "type": ["string", "null"], "format": "date" },
          "lastServiceMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 1500000 },
          "serviceIntervalMonths": { "type": ["integer", "null"], "minimum": 1, "maximum": 120 },
          "serviceIntervalDays": { "type": ["integer", "null"], "minimum": 1, "maximum": 3650 },
          "operationalStatus": {
            "type": "string",
            "enum": ["active", "standby", "in_maintenance", "off_road", "sold_or_removed"]
          },
          "assignedDriverName": { "type": ["string", "null"], "maxLength": 120 },
          "assignedDriverContact": { "type": ["string", "null"], "maxLength": 160 },
          "statusNotes": { "type": ["string", "null"], "maxLength": 1000 }
        }
      },
      "UpdateVehiclePatch": {
        "type": "object",
        "description": "All fields are optional. Provide a value to set, `null` to clear a nullable field, or omit to leave unchanged. operationalStatus cannot be null. When changing service interval units, explicitly clear the alternative field; days take precedence when both are set.",
        "properties": {
          "label": { "type": ["string", "null"], "maxLength": 80 },
          "insuranceDueDate": { "type": ["string", "null"], "format": "date" },
          "lastServiceDate": { "type": ["string", "null"], "format": "date" },
          "lastServiceMileage": { "type": ["integer", "null"], "minimum": 0, "maximum": 1500000 },
          "serviceIntervalMonths": { "type": ["integer", "null"], "minimum": 1, "maximum": 120 },
          "serviceIntervalDays": { "type": ["integer", "null"], "minimum": 1, "maximum": 3650 },
          "operationalStatus": {
            "type": "string",
            "enum": ["active", "standby", "in_maintenance", "off_road", "sold_or_removed"]
          },
          "assignedDriverName": { "type": ["string", "null"], "maxLength": 120 },
          "assignedDriverContact": { "type": ["string", "null"], "maxLength": 160 },
          "statusNotes": { "type": ["string", "null"], "maxLength": 1000 }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "example": "registration_required" }
        }
      }
    },
    "responses": {
      "Conflict": {
        "description": "Confirmation is required or the supplied confirmation is invalid, stale, replayed or bound to different content.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                { "$ref": "#/components/schemas/ActionConfirmationRequired" },
                { "$ref": "#/components/schemas/Error" }
              ]
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "A required private storage, provider configuration or service dependency is unavailable.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ProviderFailure": {
        "description": "An authorised external provider could not return or accept the requested operation.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ConfirmationConflict": {
        "description": "Confirmation is required, invalid, expired or invalidated by an event update.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                { "$ref": "#/components/schemas/ActionConfirmationRequired" },
                { "$ref": "#/components/schemas/Error" }
              ]
            }
          }
        }
      },
      "BadRequest": {
        "description": "The request body or query was invalid.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid Bearer access token.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "Forbidden": {
        "description": "Token does not include the required scope.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "BillingRequired": {
        "description": "The authorised Fleetkeep account does not currently have active product access.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "ServiceMisconfigured": {
        "description": "The API authentication or database service is not configured.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "NotFound": {
        "description": "The requested resource does not exist on the authorised user's account, is the wrong event type, or is immutable history for this operation.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "RateLimited": {
        "description": "Per-token rate limit exceeded (60 requests per minute).",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      }
    }
  }
}