{
  "openapi": "3.1.0",
  "info": {
    "title": "JOY Automart Public API",
    "version": "2026-09-23",
    "description": "Public, unauthenticated, read-only endpoints intentionally exposed by JOY Automart, Bangladesh's automotive commerce platform. Prices are in BDT and are exactly what an anonymous retail shopper sees. AI assistants may prefer the equivalent MCP tools at https://www.joyautomart.com/mcp (card: /.well-known/mcp/server-card.json). This document does not describe Owner/Admin, private agent, customer, order, payment-execution, deployment, or other privileged APIs."
  },
  "servers": [
    {
      "url": "https://www.joyautomart.com",
      "description": "JOY Automart production origin"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getPublicHealth",
        "summary": "Read JOY Automart API health",
        "description": "Returns a read-only service-health payload and current build identifier when available.",
        "responses": {
          "200": {
            "description": "Healthy service",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "502": {
            "description": "The public origin cannot reach the API service"
          },
          "503": {
            "description": "The Azure API proxy is not configured or temporarily unavailable"
          }
        }
      }
    },
    "/api/parts/marketplace-search": {
      "get": {
        "operationId": "searchRetailParts",
        "summary": "Search the retail parts catalogue",
        "description": "Full-text and fitment-filtered search over JOY's parts catalogue. Use portal=retail for public prices; other portals require a signed-in trade account. The q parameter is matched on ASCII terms only — for Bangla queries use the MCP search_parts tool, which interprets Bangla automotive vocabulary. Results are fitment candidates, not guarantees.",
        "parameters": [
          {
            "name": "portal",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "retail",
                "b2b"
              ],
              "default": "retail"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "make",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "chassis",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "availability",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "in_stock",
                "quote",
                "sourced"
              ]
            }
          },
          {
            "name": "price_min",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "price_max",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "name",
                "make",
                "newest",
                "price_asc",
                "price_desc"
              ],
              "default": "relevance"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartSearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "A protected portal was requested without a trade session"
          }
        }
      }
    },
    "/api/marketplace/products/{part_id}": {
      "get": {
        "operationId": "getRetailPart",
        "summary": "Read one catalogue part",
        "description": "Canonical public product detail: BDT price, stock, minimum order quantity, verified offers and bulk price breaks, priced by the same authority as checkout.",
        "parameters": [
          {
            "name": "part_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "portal",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "retail",
                "b2b"
              ],
              "default": "retail"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "No such part"
          }
        }
      }
    },
    "/api/vehicle-commerce/cars": {
      "get": {
        "operationId": "searchVehicles",
        "summary": "Search JOY Auto Exchange vehicles for sale",
        "description": "Public vehicle listings in Bangladesh. Only stated listing facts are returned; unknown values stay empty.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "make",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "fuel_type",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "verified_only",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "min_year",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max_year",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "latest",
                "price_asc",
                "price_desc",
                "year_desc"
              ],
              "default": "latest"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 18
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VehicleSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/payments/gateways/retail_marketplace/catalog": {
      "get": {
        "operationId": "getRetailBuyingTerms",
        "summary": "Read retail payment and delivery terms",
        "description": "Server-authoritative retail terms: payment methods (card, mobile banking via bKash/Nagad/Rocket, cash on delivery with its fee and ceiling), delivery zones and fees, minimum order, free-delivery threshold and VAT. All money values are BDT.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/feed": {
      "get": {
        "operationId": "getAgentProductFeed",
        "summary": "Agent Product Feed: every sellable retail SKU",
        "description": "Paginated JSON export of every SKU a shopper can buy right now (price set, stock at or above minimum order, verified fulfilment, not suppressed). Prices in BDT, exactly as the storefront charges. Intended for AI shopping agents and merchant-feed importers.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 60
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFeedPage"
                }
              }
            }
          },
          "503": {
            "description": "Feed temporarily unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": [
          "ok",
          "service",
          "status",
          "timestamp",
          "build_hash"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "service": {
            "type": "string"
          },
          "app": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "build_hash": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Marketplace": {
        "type": "object",
        "description": "Public, portal-specific commerce block.",
        "properties": {
          "display_price_bdt": {
            "type": [
              "number",
              "null"
            ]
          },
          "price_label": {
            "type": [
              "string",
              "null"
            ]
          },
          "availability": {
            "type": "string",
            "enum": [
              "in_stock",
              "fitment_review",
              "sourced_on_request",
              "quote_required"
            ]
          },
          "stock_on_hand": {
            "type": "integer"
          },
          "moq": {
            "type": "integer"
          },
          "sellable": {
            "type": "boolean"
          },
          "b2b": {
            "type": "object",
            "additionalProperties": true,
            "description": "Bulk quantity price breaks."
          }
        },
        "additionalProperties": true
      },
      "Part": {
        "type": "object",
        "properties": {
          "part_id": {
            "type": "string"
          },
          "part_name": {
            "type": "string"
          },
          "taxonomy": {
            "type": "object",
            "additionalProperties": true
          },
          "compatibility_matrix": {
            "description": "Fitment candidates by make, model and chassis."
          },
          "marketplace": {
            "$ref": "#/components/schemas/Marketplace"
          }
        },
        "additionalProperties": true
      },
      "PartSearchResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Part"
            }
          }
        },
        "additionalProperties": true
      },
      "PartDetailResponse": {
        "type": "object",
        "properties": {
          "portal": {
            "type": "string"
          },
          "item": {
            "$ref": "#/components/schemas/Part"
          },
          "offer_count": {
            "type": "integer"
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "Vehicle": {
        "type": "object",
        "properties": {
          "listing_id": {
            "type": "string"
          },
          "make": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "trim": {
            "type": "string"
          },
          "year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "price_bdt": {
            "type": [
              "number",
              "null"
            ]
          },
          "mileage_km": {
            "type": [
              "number",
              "null"
            ]
          },
          "fuel_type": {
            "type": "string"
          },
          "transmission": {
            "type": "string"
          },
          "verified": {
            "type": "boolean"
          },
          "inspection_status": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "VehicleSearchResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Vehicle"
            }
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          },
          "sort": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "AgentFeedItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "oem_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "warranty_months": {
            "type": [
              "integer",
              "null"
            ]
          },
          "price": {
            "type": "object",
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "currency": {
                "type": "string",
                "const": "BDT"
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "availability": {
            "type": "string"
          },
          "stock_on_hand": {
            "type": "integer"
          },
          "minimum_order_quantity": {
            "type": "integer"
          },
          "bulk_pricing": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "purchasable": {
            "type": "boolean"
          },
          "fitment": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": true
      },
      "AgentFeedPage": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "merchant": {
            "type": "object",
            "additionalProperties": true
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "next_page": {
            "type": [
              "integer",
              "null"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentFeedItem"
            }
          }
        }
      }
    }
  }
}