{
  "openapi": "3.0.3",
  "info": {
    "title": "PaintColorMatcher — Official Public REST & MCP API",
    "version": "1.0.1",
    "description": "PaintColorMatcher is an architectural colorimetry workbench indexing 11,249 official North American paint swatches across Sherwin-Williams, Benjamin Moore, and Behr. Instead of naive sRGB Euclidean distance, it computes perceptual CIE Delta-E 2000 (ΔE00), Light Reflectance Value (LRV), undertone classification, and Bradford CAT16 chromatic adaptation from 2700K warm LED to 5000K daylight. Built for interior designers, homeowners, and painting contractors, running 100% client-side photo analysis with public REST and MCP color-matching APIs.",
    "contact": {
      "name": "PaintColorMatcher",
      "url": "https://paintcolormatcher.com",
      "email": "admin@paintcolormatcher.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "externalDocs": {
    "description": "PaintColorMatcher Official Web Workbench",
    "url": "https://paintcolormatcher.com"
  },
  "servers": [
    {
      "url": "https://paintcolormatcher.com",
      "description": "Production Cloudflare Global Edge"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optional API Key for Albato / automation tracking (e.g. pk_live_paintcolormatcher_2026)"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/api/v1/me": {
      "get": {
        "operationId": "verifyApiConnection",
        "summary": "Verify PaintColorMatcher API Key & Service Health",
        "description": "Authentication test and metadata endpoint for Albato App Integrator, RapidAPI, Make, and custom workflows.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "responses": {
          "200": {
            "description": "Authenticated connection status and tool count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "authenticated": {
                      "type": "boolean",
                      "example": true
                    },
                    "service": {
                      "type": "string",
                      "example": "PaintColorMatcher"
                    },
                    "domain": {
                      "type": "string",
                      "example": "paintcolormatcher.com"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.1"
                    },
                    "toolsCount": {
                      "type": "integer",
                      "example": 8
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "listAvailableTools",
        "summary": "List All PaintColorMatcher Read-Only Tools & Schemas",
        "responses": {
          "200": {
            "description": "Array of available read-only tools"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "getMcpServerMetadata",
        "summary": "Get PaintColorMatcher MCP Server Metadata",
        "responses": {
          "200": {
            "description": "MCP Server metadata and Grade-A tool annotations"
          }
        }
      },
      "post": {
        "operationId": "invokeMcpJsonRpc",
        "summary": "Execute Streamable HTTP JSON-RPC 2.0 MCP Request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "example": "2.0"
                  },
                  "id": {
                    "type": "integer",
                    "example": 1
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "initialize",
                      "tools/list",
                      "tools/call"
                    ],
                    "example": "tools/list"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response envelope"
          }
        }
      }
    },
    "/api/v1/tools/match_hex_to_paint_colors": {
      "post": {
        "operationId": "match_hex_to_paint_colors",
        "summary": "HEX to Paint Color CIEDE2000 Matcher (11,249 Swatches)",
        "description": "Convert any HEX color code into the closest official Sherwin-Williams, Benjamin Moore, and Behr paint colors using scientific CIEDE2000 (ΔE00) color difference, LRV, and undertone classification.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hex": {
                    "type": "string",
                    "description": "6-digit HEX color code (e.g. \"#EAE6DF\" or \"7A8B8B\")"
                  },
                  "brand": {
                    "type": "string",
                    "enum": [
                      "all",
                      "sherwin-williams",
                      "benjamin-moore",
                      "behr"
                    ],
                    "description": "Filter by paint brand or search across all 3 major brands (default: \"all\")"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Maximum number of matches to return (1 to 15, default: 6)"
                  }
                },
                "required": [
                  "hex"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from match_hex_to_paint_colors"
          }
        }
      }
    },
    "/api/v1/tools/find_cross_brand_paint_equivalent": {
      "post": {
        "operationId": "find_cross_brand_paint_equivalent",
        "summary": "Cross-Brand Paint Color Equivalent & Dupe Finder",
        "description": "Find the closest cross-brand paint color equivalents (dupes) across Sherwin-Williams, Benjamin Moore, and Behr by paint name or code (e.g. \"SW 7029\", \"Agreeable Gray\", \"OC-65\", \"Chantilly Lace\").",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Paint color name or manufacturer code (e.g. \"Agreeable Gray\", \"SW 7029\", \"HC-172\", \"Swiss Coffee\")"
                  },
                  "target_brand": {
                    "type": "string",
                    "enum": [
                      "all",
                      "sherwin-williams",
                      "benjamin-moore",
                      "behr"
                    ],
                    "description": "Target brand to match into (default: \"all\")"
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from find_cross_brand_paint_equivalent"
          }
        }
      }
    },
    "/api/v1/tools/calculate_ciede2000_swatch_distance": {
      "post": {
        "operationId": "calculate_ciede2000_swatch_distance",
        "summary": "Scientific CIEDE2000 (ΔE00) Color Difference Calculator",
        "description": "Compute exact CIE L*a*b* coordinates, Light Reflectance Value (LRV), and perceptual CIEDE2000 (ΔE00) distance between any two HEX colors with commercial paint-matching tolerance grading.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hexA": {
                    "type": "string",
                    "description": "First 6-digit HEX color (e.g. \"#D1CBC1\")"
                  },
                  "hexB": {
                    "type": "string",
                    "description": "Second 6-digit HEX color (e.g. \"#CFC9BF\")"
                  }
                },
                "required": [
                  "hexA",
                  "hexB"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from calculate_ciede2000_swatch_distance"
          }
        }
      }
    },
    "/api/v1/tools/analyze_paint_lrv_and_room_exposure": {
      "post": {
        "operationId": "analyze_paint_lrv_and_room_exposure",
        "summary": "Paint LRV (Light Reflectance Value) & Compass Room Exposure Advisor",
        "description": "Evaluate how a paint color LRV (0–100) behaves in North-facing, South-facing, East-facing, West-facing, or windowless rooms and HOA exterior LRV restrictions.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lrv": {
                    "type": "number",
                    "description": "Paint Light Reflectance Value from 0 to 100 (e.g. 60 for Agreeable Gray, 83 for Alabaster)"
                  },
                  "roomExposure": {
                    "type": "string",
                    "enum": [
                      "north",
                      "south",
                      "east",
                      "west",
                      "exterior"
                    ],
                    "description": "Primary natural light compass exposure or exterior application"
                  }
                },
                "required": [
                  "lrv",
                  "roomExposure"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from analyze_paint_lrv_and_room_exposure"
          }
        }
      }
    },
    "/api/v1/tools/calculate_room_paint_gallons_estimator": {
      "post": {
        "operationId": "calculate_room_paint_gallons_estimator",
        "summary": "Interior Wall & Trim Paint Gallon Coverage Estimator",
        "description": "Calculate exact gallons and quarts of wall paint and primer needed after subtracting doors and windows at 350–400 sq ft per gallon.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wallPerimeterFeet": {
                    "type": "number",
                    "description": "Total room perimeter in feet (e.g. 52 for a 12x14 ft room)"
                  },
                  "ceilingHeightFeet": {
                    "type": "number",
                    "description": "Ceiling height in feet (default: 8 or 9)"
                  },
                  "coats": {
                    "type": "number",
                    "description": "Number of finish coats (default: 2)"
                  },
                  "doorsCount": {
                    "type": "number",
                    "description": "Number of standard doors (21 sq ft each, default: 2)"
                  },
                  "windowsCount": {
                    "type": "number",
                    "description": "Number of standard windows (15 sq ft each, default: 2)"
                  }
                },
                "required": [
                  "wallPerimeterFeet",
                  "ceilingHeightFeet"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from calculate_room_paint_gallons_estimator"
          }
        }
      }
    },
    "/api/v1/tools/recommend_paint_sheen_finish": {
      "post": {
        "operationId": "recommend_paint_sheen_finish",
        "summary": "Architectural Paint Sheen & Finish Selector (Flat to Semi-Gloss)",
        "description": "Recommend optimal paint sheen (Flat/Matte, Eggshell, Satin, Semi-Gloss, Cabinet Urethane Enamel) based on room humidity, traffic scrubbability, and drywall imperfection hiding.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "surfaceOrRoom": {
                    "type": "string",
                    "enum": [
                      "ceiling",
                      "living-bedroom",
                      "kitchen-bathroom",
                      "hallway-kids",
                      "trim-doors-cabinets",
                      "exterior-siding"
                    ],
                    "description": "Target architectural surface or room type"
                  }
                },
                "required": [
                  "surfaceOrRoom"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from recommend_paint_sheen_finish"
          }
        }
      }
    },
    "/api/v1/tools/simulate_kelvin_lighting_undertone_shift": {
      "post": {
        "operationId": "simulate_kelvin_lighting_undertone_shift",
        "summary": "2700K–5000K LED Bulb Color Temperature Undertone Shift Guide",
        "description": "Predict how warm 2700K incandescent/LED, 3000K soft white, 3500K neutral, and 5000K daylight bulbs shift warm greige, green-gray, violet-gray, and creamy white undertones.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "undertone": {
                    "type": "string",
                    "enum": [
                      "warm-yellow-cream",
                      "greige-taupe",
                      "green-gray",
                      "blue-violet-gray",
                      "crisp-neutral-white"
                    ],
                    "description": "Base undertone family of the paint swatch"
                  },
                  "kelvin": {
                    "type": "number",
                    "description": "LED bulb correlated color temperature in Kelvin (e.g. 2700, 3000, 3500, 4000, 5000)"
                  }
                },
                "required": [
                  "undertone",
                  "kelvin"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from simulate_kelvin_lighting_undertone_shift"
          }
        }
      }
    },
    "/api/v1/tools/generate_coordinating_trim_and_accent_palette": {
      "post": {
        "operationId": "generate_coordinating_trim_and_accent_palette",
        "summary": "Coordinating White Trim, Ceiling & Accent Palette Builder",
        "description": "Generate designer-tested coordinating trim white, ceiling flat white, and contrasting accent colors matched to a main wall HEX or paint swatch.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wallHex": {
                    "type": "string",
                    "description": "Main wall 6-digit HEX color (e.g. \"#D1CBC1\")"
                  }
                },
                "required": [
                  "wallHex"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON output from generate_coordinating_trim_and_accent_palette"
          }
        }
      }
    }
  }
}