{
  "openapi": "3.1.0",
  "info": {
    "title": "ManSarathi Public Agent API",
    "version": "1.0.0",
    "description": "Read-only endpoints for AI assistants and Custom GPT Actions. ManSarathi sells premium Indian stationery — journals, planners, pencils, and gift bundles from Hyderabad. Prices in INR (paise internally). Purchases complete on https://mansarathi.com in the user's browser.",
    "contact": {
      "name": "ManSarathi Support",
      "email": "support@mansarathi.com",
      "url": "https://mansarathi.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.mansarathi.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "List active stationery products",
        "description": "Returns paginated active products with names, slugs, INR prices, categories, and availability. Use when browsing the catalog or filtering by category.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Category slug filter, e.g. journals, planners, gifts-bundles",
            "schema": { "type": "string" }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "Tag slug filter",
            "schema": { "type": "string" }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (default 1)",
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (default 20, max 48 recommended for assistants)",
            "schema": { "type": "integer", "minimum": 1, "maximum": 48, "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Product list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/products/{slug}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get one product by slug",
        "description": "Full product details including variants, prices in INR, images, and inventory. Example slugs: money-log, daily-book, dream-planner, upahaar-bundle, bachpan-pencil-set, notebook.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Product URL slug",
            "schema": { "type": "string", "example": "money-log" }
          }
        ],
        "responses": {
          "200": {
            "description": "Product detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "404": {
            "description": "Product not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/products/{slug}/serviceability": {
      "get": {
        "operationId": "checkDelivery",
        "summary": "Check courier delivery to an Indian pincode",
        "description": "Returns whether the product can ship to a six-digit Indian pincode via courier partners.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "money-log" }
          },
          {
            "name": "pincode",
            "in": "query",
            "required": true,
            "description": "Six-digit Indian pincode",
            "schema": { "type": "string", "pattern": "^\\d{6}$", "example": "500032" }
          }
        ],
        "responses": {
          "200": {
            "description": "Serviceability result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ServiceabilityResponse" }
              }
            }
          }
        }
      }
    },
    "/api/agent/buying-guide": {
      "get": {
        "operationId": "getBuyingGuide",
        "summary": "Intent-based product recommendations",
        "description": "Returns structured buying recommendations for expense tracking, daily journaling, goal planning, gifting, pencils, and add-ons. Use when the user asks which ManSarathi product fits their need.",
        "responses": {
          "200": {
            "description": "Buying guide recommendations",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BuyingGuideResponse" }
              }
            }
          }
        }
      }
    },
    "/api/recommendations": {
      "get": {
        "operationId": "getRecommendations",
        "summary": "Personalized product recommendations",
        "description": "Returns curated product recommendations. May use anonymous global bestsellers when no user session is present.",
        "responses": {
          "200": {
            "description": "Recommendation list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecommendationsResponse" }
              }
            }
          }
        }
      }
    },
    "/api/orders/track/{displayId}": {
      "get": {
        "operationId": "trackOrder",
        "summary": "Track order status by display ID",
        "description": "Public order tracking using ManSarathi display ID (format MS-XXXXXXXX). Returns status, AWB, and courier tracking URL when available. No PII beyond order reference.",
        "parameters": [
          {
            "name": "displayId",
            "in": "path",
            "required": true,
            "description": "Order display ID, e.g. MS-A1B2C3D4",
            "schema": { "type": "string", "example": "MS-A1B2C3D4" }
          }
        ],
        "responses": {
          "200": {
            "description": "Order tracking snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrderTrackResponse" }
              }
            }
          },
          "404": {
            "description": "Order not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string" },
          "code": { "type": "string" }
        },
        "required": ["success", "error", "code"]
      },
      "ProductListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ProductSummary" }
          },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": { "$ref": "#/components/schemas/ProductSummary" }
        }
      },
      "ProductSummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "pricePaise": { "type": "integer", "description": "Price in paise (₹799 = 79900)" },
          "priceDisplay": { "type": "string", "description": "Formatted INR price" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "hasMore": { "type": "boolean" }
        }
      },
      "ServiceabilityResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": {
            "type": "object",
            "properties": {
              "serviceable": { "type": "boolean" },
              "pincode": { "type": "string" }
            }
          }
        }
      },
      "BuyingGuideResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": {
            "type": "object",
            "properties": {
              "brand": { "type": "string" },
              "tagline": { "type": "string" },
              "recommendations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "intent": { "type": "string" },
                    "keywords": { "type": "array", "items": { "type": "string" } },
                    "productSlug": { "type": "string" },
                    "name": { "type": "string" },
                    "priceDisplay": { "type": "string" },
                    "reason": { "type": "string" },
                    "productUrl": { "type": "string", "format": "uri" },
                    "buyingGuideUrl": { "type": "string", "format": "uri" }
                  }
                }
              },
              "membership": { "type": "object" },
              "storefrontUrl": { "type": "string", "format": "uri" },
              "checkoutNote": { "type": "string" },
              "supportEmail": { "type": "string", "format": "email" }
            }
          }
        }
      },
      "RecommendationsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": { "type": "array", "items": { "type": "object" } }
        }
      },
      "OrderTrackResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": {
            "type": "object",
            "properties": {
              "displayId": { "type": "string" },
              "status": { "type": "string" },
              "awb": { "type": "string", "nullable": true },
              "courierName": { "type": "string", "nullable": true },
              "trackingUrl": { "type": "string", "format": "uri", "nullable": true }
            }
          }
        }
      }
    }
  },
  "x-ai-policy": "https://mansarathi.com/ai.txt",
  "x-llms-txt": "https://mansarathi.com/llms.txt",
  "x-privacy-policy": "https://mansarathi.com/privacy-policy"
}