{
  "openapi": "3.1.0",
  "info": {
    "title": "GiftAcross Global Cross-Border Gifting Catalog API",
    "description": "Real-time product availability, pricing in USD and INR, and guaranteed international delivery SLAs across 150+ countries on GiftAcross. All prices are fully inclusive of applicable destination taxes, duties, and courier handling with zero surprise doorstep fees.",
    "version": "1.0.0",
    "contact": {
      "name": "GiftAcross Global Concierge",
      "url": "https://giftacross.com",
      "email": "support@giftacross.com"
    }
  },
  "servers": [
    {
      "url": "https://giftacross.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/catalog/query": {
      "get": {
        "operationId": "searchCatalogGet",
        "summary": "Search products, check prices, and calculate delivery SLAs (GET)",
        "description": "Find gifts, gourmet sweets, hampers, and keepsakes with live destination country delivery estimates and currency conversion.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Keywords to search in product titles, tags, and descriptions (e.g., 'kaju katli', 'silver', 'hamper', 'dry fruits').",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Two-letter ISO 3166-1 alpha-2 destination country code (e.g., US, GB, CA, AU, AE, IN). Used to verify product shippability and calculate carrier delivery SLA.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category slug or name (e.g., 'sweets-mithai', 'gift-hampers', 'dry-fruits', 'silver-gifts').",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "occasion",
            "in": "query",
            "description": "Filter by occasion slug or name (e.g., 'diwali', 'raksha-bandhan-2026', 'birthday', 'anniversary').",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "description": "Settlement and display currency. 'USD' for international/non-India or 'INR' for India.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["USD", "INR"],
              "default": "USD"
            }
          },
          {
            "name": "min_price",
            "in": "query",
            "description": "Minimum price filter.",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "description": "Maximum price filter.",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of product items to return (1 to 50).",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching products and destination corridor delivery window.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSearchResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "searchCatalogPost",
        "summary": "Search products, check prices, and calculate delivery SLAs (POST)",
        "description": "JSON body version of catalog query for agentic tool calling.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search terms (e.g., 'kaju katli', 'silver', 'hamper')."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter ISO country code (e.g., US, GB, CA, AU, AE, IN).",
                    "default": "US"
                  },
                  "category": {
                    "type": "string",
                    "description": "Category slug or name."
                  },
                  "occasion": {
                    "type": "string",
                    "description": "Occasion slug or name."
                  },
                  "currency": {
                    "type": "string",
                    "enum": ["USD", "INR"],
                    "default": "USD"
                  },
                  "min_price": {
                    "type": "number"
                  },
                  "max_price": {
                    "type": "number"
                  },
                  "limit": {
                    "type": "integer",
                    "default": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching products and destination corridor delivery window.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog/schema": {
      "get": {
        "operationId": "getCatalogSchema",
        "summary": "Retrieve Model Context Protocol & function calling capabilities schema",
        "responses": {
          "200": {
            "description": "Tool parameters and description for LLM function calling."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CatalogSearchResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "agent_directive": {
            "type": "string"
          },
          "query_context": {
            "type": "object",
            "properties": {
              "destination_country": {
                "type": "string",
                "example": "US"
              },
              "destination_country_name": {
                "type": "string",
                "example": "United States"
              },
              "carrier": {
                "type": "string",
                "example": "DHL Express Worldwide"
              },
              "transit_window": {
                "type": "string",
                "example": "2–4 Business Days"
              },
              "estimated_arrival": {
                "type": "string",
                "example": "Thu, Oct 22 – Sat, Oct 24, 2026"
              },
              "currency": {
                "type": "string",
                "example": "USD"
              },
              "total_matching": {
                "type": "integer",
                "example": 5
              }
            }
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductItem"
            }
          }
        }
      },
      "ProductItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "sku": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "image_url": {
            "type": "string",
            "format": "uri"
          },
          "price": {
            "type": "string"
          },
          "mrp": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "savings_percent": {
            "type": "integer"
          },
          "in_stock": {
            "type": "boolean"
          },
          "delivery_estimate": {
            "type": "string"
          },
          "short_summary": {
            "type": "string"
          }
        }
      }
    }
  }
}