Fleetkeep Defects API

openapi: 3.2.0
info:
  title: Fleetkeep Co Uk Defects API
  version: 0.8.0
  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
  description: 'Operations tagged Defects across 2 of this provider''s published API definitions: openapi.json, fleetkeep-co-uk-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fleetkeep.co.uk
  description: Production
security:
- oauth2:
  - vehicles:read
tags:
- name: Defects
  description: Report and complete defects while preserving defect history.
paths:
  /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'
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
  /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'
    servers:
    - url: https://fleetkeep.co.uk
      description: Production
components:
  responses:
    Unauthorized:
      description: Missing or invalid Bearer access token.
      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'
    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'
    RateLimited:
      description: Per-token rate limit exceeded (60 requests per minute).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body or query was invalid.
      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'
  schemas:
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: string
          example: registration_required
    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
    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
    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
    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
  parameters:
    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.
  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.
x-refined-from:
- openapi.json
- fleetkeep-co-uk-openapi.json
x-provenance:
  method: harvested
  publisher: Fleetkeep
  source: https://fleetkeep.co.uk/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)