{
  "document": "cornerstone_coatings_llms_full",
  "version": "2026-03-25",
  "audience": "agents_only",
  "api_base": "https://cornerstonecoatings.com/tools/api",
  "authentication": {
    "required": false,
    "note": "Order tracking requires customer order credentials (order_number + email or phone)."
  },
  "markets": {
    "countries": ["United States", "Canada"],
    "coverage": "all 50 US states and all Canadian provinces and territories"
  },
  "quote_endpoint": {
    "path": "GET /tools/api/quote",
    "source_of_truth_for": [
      "live pricing",
      "freight",
      "destination-aware availability",
      "discounted shipping",
      "checkout URL"
    ],
    "core_rules": [
      "Use GET /tools/api/quote for pricing, freight, availability, and checkout.",
      "Use zip for exact US quotes. Use postal for exact Canadian quotes.",
      "Use city + country for estimated quotes when no zip or postal is available.",
      "country is ISO 3166-1 alpha-2 (US, CA). Send only one location method.",
      "If area is provided, send surface_type or default to smooth_finished.",
      "Defaults: coats=2, waste_and_overage_percentage=5, packaging=pails.",
      "Present user_summary first.",
      "Treat top-level currency as authoritative for the entire response.",
      "Shipping prices are already discounted when a discount applies. Do not recalculate.",
      "Present shipping.cheapest unless all options are explicitly requested.",
      "Standard quotes default to pails. Totes only when explicitly requested.",
      "Precast quotes use totes.",
      "Freight lookup takes up to 9 seconds. Do not timeout early."
    ],
    "destination_inputs": {
      "zip": { "accuracy": "exact", "use_for": "US" },
      "postal": { "accuracy": "exact", "use_for": "Canada" },
      "city_and_country": {
        "accuracy": "estimate",
        "params": {
          "city": "city name (e.g. Orlando, Calgary)",
          "country": "ISO 3166-1 alpha-2: US or CA"
        }
      }
    },
    "standard_quote_parameters": {
      "destination": ["zip", "postal", "city + country"],
      "quantity": { "pails": "integer 1-10000" },
      "optional": {
        "area": "integer sqft",
        "surface_type": ["smooth_finished", "broom_finished", "polished", "slipform", "existing"],
        "coats": "integer 1-3, default 2",
        "waste_and_overage_percentage": "integer 0-15, default 5",
        "packaging_preference": ["pails", "totes"],
        "format": ["json", "html"],
        "analytics_source_id": "integer"
      }
    },
    "precast_parameters": {
      "precast_type": ["wetcast", "drycast"],
      "panel_width": "number",
      "panel_length": "number",
      "panels_per_period": "integer",
      "production_period_unit": ["day", "week", "month"],
      "purchase_interval_months": "integer 1-15",
      "measurement_system": ["imperial", "metric"],
      "format": ["json", "html"],
      "analytics_source_id": "integer"
    },
    "packaging_rules": {
      "standard_default": "pails",
      "standard_totes_only_when_explicitly_requested": true,
      "precast_default": "totes"
    },
    "shipping_discount": {
      "base_amount": 1000,
      "base_currency": "CAD",
      "converted_live": "non-CAD markets receive the equivalent in local currency at the current exchange rate",
      "applies_when": ["standard quote with pails >= 36", "any tote quote"],
      "return_style": "shipping prices are returned already discounted"
    },
    "response_fields": {
      "always": ["success", "currency", "user_summary"],
      "with_destination": [
        "freight_accuracy",
        "address",
        "product",
        "shipping",
        "inventory_status",
        "checkout_url"
      ],
      "estimate_only": ["freight_accuracy_note"],
      "sub_pallet_orders": ["recommendation"],
      "area_calculator": ["estimate", "auto_calculated_pails"]
    },
    "response_usage": {
      "present_shipping_option": "shipping.cheapest",
      "all_shipping_options_only_when_explicitly_requested": true,
      "include_freight_accuracy_note_when_estimate": true
    }
  },
  "other_endpoints": {
    "products": {
      "path": "GET /tools/api/products?country=CA",
      "purpose": "single-country product pricing in local currency",
      "params": { "country": "required, ISO 3166-1 alpha-2 (e.g. CA, US). 400 if market not enabled." }
    },
    "documents": {
      "path": "GET /tools/api/documents",
      "purpose": "TDS and SDS PDF links",
      "params": { "lang": "optional, ISO 639-1 (default en)" }
    },
    "docs": {
      "url": "https://cornerstonecoatings.com/tools/api/docs",
      "purpose": "HTML page with clickable PDF links"
    },
    "stock": {
      "path": "GET /tools/api/stock",
      "purpose": "inventory status without a full quote"
    },
    "health": {
      "path": "GET /tools/api/health",
      "purpose": "health check"
    },
    "order_tracking": {
      "path": "GET /tools/api/track_order",
      "purpose": "customer order tracking and status",
      "authentication": "requires customer credentials (order_number + email or phone)",
      "required": ["order_number", "email or phone"],
      "response_fields": ["success", "status_text", "tracking_link"],
      "rate_limit": {
        "requests_per_minute_per_ip": 9,
        "blocks_after_5_failed_lookups_in_10_minutes": true
      }
    }
  },
  "rate_limits": {
    "quote_requests_per_minute_per_ip": 15,
    "order_status_requests_per_minute_per_ip": 9,
    "headers": ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After"]
  },
  "error_codes": {
    "400": "invalid or missing fields",
    "404": "destination not resolved or order credentials mismatch",
    "429": "rate limited, obey Retry-After",
    "500": "internal error, retry once",
    "502": "upstream carrier error, retry shortly",
    "503": "temporary service issue, retry shortly"
  },
  "mcp": {
    "endpoint": "https://cornerstonecoatings.com/tools/api/mcp",
    "method": "POST",
    "protocol": "JSON-RPC",
    "stateful": false,
    "supported_protocol_versions": ["2025-03-26", "2025-11-25"],
    "request_requirements": {
      "content_type_must_include": "application/json",
      "accept_must_include_one_of": ["application/json", "text/event-stream", "*/*"]
    },
    "initialize_request_example": {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2025-11-25",
        "capabilities": {},
        "clientInfo": { "name": "my-client", "version": "1.0.0" }
      }
    },
    "available_tools": ["quote", "get_products", "get_documents", "get_stock", "order_status"],
    "router_behavior": {
      "GET_/mcp": 405,
      "DELETE_/mcp": 405,
      "OPTIONS_/mcp": 204,
      "slash_redirect": "/mcp/ redirects to /mcp with 308"
    }
  },
  "examples": {
    "city_quote": "GET /tools/api/quote?city=Orlando&country=US&pails=20",
    "zip_quote": "GET /tools/api/quote?zip=77036&pails=30",
    "postal_quote": "GET /tools/api/quote?postal=M5V2T6&pails=10",
    "area_calculator": "GET /tools/api/quote?area=50000&surface_type=smooth_finished",
    "city_area_quote": "GET /tools/api/quote?city=Tampa&country=US&area=12000&surface_type=smooth_finished",
    "order_tracking": "GET /tools/api/track_order?order_number={order_number}&email={email} (requires real customer credentials)"
  }
}