{
  "openapi": "3.1.0",
  "info": {
    "title": "Direct Mini Mix AI Telephone Booking API",
    "version": "1.1.0",
    "description": "Controlled integration API for approved AI telephone and automation partners. API keys are generated by DMM and stored as hashes in the DMM database."
  },
  "servers": [
    {
      "url": "https://dmm.aigoat.uk/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "BookingRequest": {
        "type": "object",
        "required": [
          "date",
          "time",
          "durationHours",
          "items"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "example": "Jobix"
          },
          "externalReference": {
            "type": "string"
          },
          "customerId": {
            "type": "string",
            "format": "uuid"
          },
          "customer": {
            "type": "object"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string",
            "example": "09:30"
          },
          "durationHours": {
            "type": "number",
            "minimum": 0.25
          },
          "driverId": {
            "type": "string"
          },
          "truckId": {
            "type": "string"
          },
          "paymentType": {
            "type": "string"
          },
          "customerReference": {
            "type": "string"
          },
          "delivery": {
            "type": "object"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "productId",
                "quantity"
              ],
              "properties": {
                "productId": {
                  "type": "string"
                },
                "quantity": {
                  "type": "number"
                },
                "price": {
                  "type": "number"
                }
              }
            }
          },
          "requiredDataAnswers": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "notes": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "API health",
        "responses": {
          "200": {
            "description": "API status"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON"
          }
        }
      }
    },
    "/catalog": {
      "get": {
        "summary": "DMM booking catalogue",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Products and booking metadata"
          }
        }
      }
    },
    "/customers/search": {
      "get": {
        "summary": "Search customers",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching customers"
          }
        }
      }
    },
    "/availability": {
      "get": {
        "summary": "Driver and truck availability for a requested time window",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "time",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "09:30"
            }
          },
          {
            "name": "durationHours",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0.25,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available drivers, trucks, bookable pairs and conflicting jobs"
          }
        }
      }
    },
    "/bookings": {
      "post": {
        "summary": "Create a DMM Job or automatically fall back to a Quote",
        "description": "If the requested Driver/Truck is unavailable (or no resources were selected), the lead is retained as a DMM Quote for office follow-up.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "BOOKED or QUOTE_CREATED"
          },
          "400": {
            "description": "Validation error"
          }
        }
      }
    },
    "/quotes": {
      "post": {
        "summary": "Explicitly create an office follow-up Quote",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quote created"
          }
        }
      }
    },
    "/bookings/{id}": {
      "get": {
        "summary": "Get booking",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Booking"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    }
  }
}