openapi: 3.1.0
info:
  title: Wrenchli API
  description: AI-powered vehicle symptom assessments, repair cost estimation, vehicle valuation, maintenance scheduling, and service provider search. Analyze symptoms, get repair cost estimates, urgency ratings, vehicle market values, and actionable recommendations.
  version: 1.3.0
servers:
  - url: https://aunrktvltmyrxtdygykt.supabase.co/functions/v1
paths:
  /api-diagnose:
    post:
      operationId: diagnoseVehicle
      summary: Assess vehicle problems from symptoms
      description: Provide vehicle symptoms and vehicle info to receive a structured assessment with urgency, cost estimates, safety advice, and repair recommendations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - symptoms
                - vehicle
              properties:
                symptoms:
                  type: array
                  items:
                    type: string
                  description: List of symptoms (e.g. "grinding noise when braking")
                vehicle:
                  type: object
                  required:
                    - year
                    - make
                    - model
                  properties:
                    year:
                      type: integer
                      description: Vehicle model year
                    make:
                      type: string
                      description: Vehicle manufacturer (e.g. Toyota, Ford)
                    model:
                      type: string
                      description: Vehicle model (e.g. Camry, F-150)
                    mileage:
                      type: integer
                      description: Current odometer reading in miles
                location:
                  type: string
                  description: ZIP code or city for localized shop recommendations
      responses:
        "200":
          description: Successful assessment
          content:
            application/json:
              schema:
                type: object
                properties:
                  diagnosis:
                    type: object
                    properties:
                      probable_issue:
                        type: string
                      description:
                        type: string
                      urgency:
                        type: string
                        enum: [low, medium, high]
                      cost_estimate:
                        type: object
                        properties:
                          min:
                            type: number
                          max:
                            type: number
                  recommendations:
                    type: object
                    properties:
                      immediate_action:
                        type: string
                      safety_advice:
                        type: string
                      diy_feasible:
                        type: boolean
                  wrenchli_services:
                    type: object
                    properties:
                      get_quotes_url:
                        type: string
                      find_shops_url:
                        type: string
        "400":
          description: Invalid request
        "401":
          description: Missing API key
        "403":
          description: Invalid or deactivated API key
        "429":
          description: Rate limit exceeded
      security:
        - apiKey: []
  /api-estimate-repair:
    post:
      operationId: estimateRepairCost
      summary: Get AI-powered repair cost estimate
      description: Provide a symptom assessment and vehicle info with a ZIP code to receive a localized repair cost estimate with parts/labor breakdown.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - diagnosis_title
                - zip_code
              properties:
                diagnosis_title:
                  type: string
                  description: The assessed issue (e.g. "Worn Brake Pads")
                diagnosis_code:
                  type: string
                  description: DTC code if applicable (e.g. "P0420")
                vehicle_year:
                  type: string
                  description: Vehicle model year
                vehicle_make:
                  type: string
                  description: Vehicle manufacturer
                vehicle_model:
                  type: string
                  description: Vehicle model
                vehicle_trim:
                  type: string
                  description: Vehicle trim level
                zip_code:
                  type: string
                  description: 5-digit US ZIP code for localized pricing
                diy_feasibility:
                  type: string
                  description: DIY difficulty (easy, moderate, advanced)
                urgency:
                  type: string
                  description: Urgency level (low, medium, high)
      responses:
        "200":
          description: Successful cost estimate
          content:
            application/json:
              schema:
                type: object
                properties:
                  metro_area:
                    type: string
                  cost_low:
                    type: number
                  cost_high:
                    type: number
                  parts_estimate:
                    type: string
                  labor_estimate:
                    type: string
                  labor_hours:
                    type: string
                  regional_notes:
                    type: string
                  what_to_expect:
                    type: string
                  warranty_note:
                    type: string
        "400":
          description: Invalid request
        "401":
          description: Missing API key
        "403":
          description: Invalid or deactivated API key
        "429":
          description: Rate limit exceeded
      security:
        - apiKey: []
  /api-vehicle-value:
    post:
      operationId: getVehicleValue
      summary: Get vehicle market value and repair-vs-replace analysis
      description: Provide vehicle details and mileage to receive an estimated market value with depreciation breakdown, market trend analysis, and optional repair-vs-replace recommendation when a repair cost is included.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vehicle
              properties:
                vehicle:
                  type: object
                  required:
                    - year
                    - make
                    - model
                    - mileage
                  properties:
                    year:
                      type: integer
                      description: Vehicle model year (1990–current+1)
                    make:
                      type: string
                      description: Vehicle manufacturer (e.g. Honda, Toyota)
                    model:
                      type: string
                      description: Vehicle model (e.g. Accord, Camry)
                    mileage:
                      type: integer
                      description: Current odometer reading in miles (0–500000)
                    zipCode:
                      type: string
                      description: 5-digit US ZIP code for regional context
                repair_cost:
                  type: number
                  description: Optional repair cost to trigger repair-vs-replace analysis
      responses:
        "200":
          description: Vehicle valuation with optional repair analysis
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_value:
                    type: number
                    description: Estimated current market value in USD
                  confidence:
                    type: integer
                    description: Confidence score (0–100)
                  value_breakdown:
                    type: object
                    properties:
                      base_msrp:
                        type: number
                      age_depreciation:
                        type: number
                      mileage_adjustment:
                        type: number
                      regional_adjustment:
                        type: number
                  market_analysis:
                    type: object
                    properties:
                      trend:
                        type: string
                        enum: [up, down, stable]
                      optimal_sell_window:
                        type: boolean
                      trade_vs_repair:
                        type: object
                        properties:
                          repair_percentage:
                            type: integer
                          recommendation:
                            type: string
                            enum: [repair_recommended, consider_replacement, replace_recommended]
                          reasoning:
                            type: string
                  wrenchli_services:
                    type: object
                    properties:
                      detailed_analysis_url:
                        type: string
                      get_quotes_url:
                        type: string
                      garage_management_url:
                        type: string
        "400":
          description: Invalid request
        "401":
          description: Missing API key
        "403":
          description: Invalid or deactivated API key
        "429":
          description: Rate limit exceeded
      security:
        - apiKey: []
  /api-maintenance-schedule:
    post:
      operationId: getMaintenanceSchedule
      summary: Get vehicle maintenance schedule and upcoming services
      description: Provide vehicle make and current mileage to receive a full maintenance schedule with brand-specific adjustments, upcoming service items sorted by urgency, and cost estimates. Optionally provide last service records to calculate accurate due dates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vehicle
              properties:
                vehicle:
                  type: object
                  required:
                    - make
                    - mileage
                  properties:
                    make:
                      type: string
                      description: Vehicle manufacturer (e.g. Toyota, BMW, Tesla)
                    model:
                      type: string
                      description: Vehicle model (e.g. Camry, 3 Series)
                    year:
                      type: integer
                      description: Vehicle model year
                    mileage:
                      type: integer
                      description: Current odometer reading in miles (0–500000)
                last_services:
                  type: array
                  description: Optional array of last service records for accurate due-date calculation
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        description: Service type key (e.g. oil_change, brake_inspection)
                      mileage:
                        type: integer
                        description: Mileage when service was last performed
      responses:
        "200":
          description: Maintenance schedule with upcoming services
          content:
            application/json:
              schema:
                type: object
                properties:
                  vehicle_summary:
                    type: object
                  full_schedule:
                    type: array
                    items:
                      type: object
                  upcoming_services:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        label:
                          type: string
                        due_mileage:
                          type: integer
                        miles_until_due:
                          type: integer
                        priority:
                          type: string
                          enum: [overdue, urgent, soon, upcoming]
                        estimated_cost_low:
                          type: number
                        estimated_cost_high:
                          type: number
                  summary:
                    type: object
                    properties:
                      total_items:
                        type: integer
                      overdue_count:
                        type: integer
                      urgent_count:
                        type: integer
                      estimated_total_cost_low:
                        type: number
                      estimated_total_cost_high:
                        type: number
        "400":
          description: Invalid request
        "401":
          description: Missing API key
        "403":
          description: Invalid or deactivated API key
        "429":
          description: Rate limit exceeded
      security:
        - apiKey: []
  /api-providers:
    get:
      operationId: findServiceProviders
      summary: Find nearby service providers with smart matching
      description: >
        Search for auto repair shops by location with optional filters for service type, price range, and vehicle make.
        Luxury brands (BMW, Mercedes-Benz, Audi, Lexus) are automatically matched with European/luxury specialists.
        Results are drawn from shops participating in Wrenchli's free referral pilot,
        which is enrolling independent shops nationally.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
          description: >
            ZIP code or city name. Supported ZIP codes: 48091, 48009, 48084, 48315, 48104,
            48124, 48150, 48201, 48075, 48067, 48334, 48375, 48187.
            City names also accepted (e.g. "Birmingham", "Royal Oak", "Farmington Hills").
        - name: service_type
          in: query
          required: false
          schema:
            type: string
          description: Type of service needed (e.g. brakes, engine, general)
        - name: radius_miles
          in: query
          required: false
          schema:
            type: integer
            default: 25
          description: Search radius in miles
        - name: price_range
          in: query
          required: false
          schema:
            type: string
            enum: [budget, mid, premium]
          description: Filter by price tier
        - name: vehicle_make
          in: query
          required: false
          schema:
            type: string
          description: Vehicle make for specialist matching (e.g. BMW)
      responses:
        "200":
          description: List of matching service providers
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        rating:
                          type: number
                        review_count:
                          type: integer
                        address:
                          type: string
                        phone:
                          type: string
                        distance_miles:
                          type: number
                        specialties:
                          type: array
                          items:
                            type: string
                        price_tier:
                          type: string
                          enum: [budget, mid, premium]
                        response_time:
                          type: string
                        availability:
                          type: string
                          enum: [same_day, next_day, within_week]
                        wrenchli_verified:
                          type: boolean
                        quote_url:
                          type: string
                  search_params:
                    type: object
                  wrenchli_services:
                    type: object
        "400":
          description: Missing location parameter
        "401":
          description: Missing API key
        "403":
          description: Invalid or deactivated API key
        "429":
          description: Rate limit exceeded
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key