{
  "openapi": "3.1.0",
  "info": {
    "title": "GiveRefer ReferralGPT API",
    "version": "1.2.0",
    "description": "API contract used by ReferralGPT to search and retrieve referral programs from GiveRefer. Includes structured store content: taglines, how-it-works steps, key features, FAQs, stats, category and supported countries."
  },
  "servers": [
    {
      "url": "https://giverefer.com/api",
      "description": "Production API"
    }
  ],
  "paths": {
    "/referral/search": {
      "get": {
        "operationId": "searchReferral",
        "summary": "Search referral by brand name or website domain",
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Brand name or slug (for example: uber). A domain passed here is also accepted. Required unless `domain` is given."
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The brand's own website domain (for example: uber.com). A full URL such as https://www.uber.com/ride is accepted and normalised. Required unless `brand` is given."
          }
        ],
        "responses": {
          "200": {
            "description": "Referral match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchReferralResponse"
                },
                "examples": {
                  "uber": {
                    "value": {
                      "brand": "Uber",
                      "store_slug": "uber",
                      "domain": "uber.com",
                      "bonus": "\u20b9200 ride credit",
                      "tagline": "Free rides for new users",
                      "description": "Get \u20b9200 ride credit using referral",
                      "category": "ride-hailing",
                      "url": "https://giverefer.com/store/uber"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Brand not found"
          }
        }
      }
    },
    "/referral/suggest": {
      "get": {
        "operationId": "suggestReferral",
        "summary": "Suggest referrals based on user intent",
        "parameters": [
          {
            "name": "intent",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Intent phrase (for example: food delivery)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggested referrals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SuggestReferralItem"
                  }
                },
                "examples": {
                  "foodDelivery": {
                    "value": [
                      {
                        "brand": "Swiggy",
                        "bonus": "\u20b9150 off",
                        "url": "https://giverefer.com/store/swiggy"
                      },
                      {
                        "brand": "Zomato",
                        "bonus": "\u20b9100 free delivery",
                        "url": "https://giverefer.com/store/zomato"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/referral/{store_slug}/latest-codes": {
      "get": {
        "operationId": "getLatestReferralCodes",
        "summary": "Get latest referral codes by store slug",
        "parameters": [
          {
            "name": "store_slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Latest referral codes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralCodesResponse"
                },
                "examples": {
                  "latestZeptoCodes": {
                    "value": {
                      "brand": "Zepto",
                      "referral_codes": [
                        {
                          "code": "https://zepto-prod.onelink.me/tC90/5u3xri6m",
                          "click_count": 14,
                          "updated_at": "2026-03-11T10:05:07.000000Z"
                        },
                        {
                          "code": "ADITY520ELI",
                          "click_count": 0,
                          "updated_at": "2026-03-05T20:45:44.000000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Store not found"
          }
        }
      }
    },
    "/referral/{store_slug}/top-clicked-codes": {
      "get": {
        "operationId": "getTopClickedReferralCodes",
        "summary": "Get most-clicked referral codes by store slug",
        "parameters": [
          {
            "name": "store_slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top-clicked referral codes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralCodesResponse"
                },
                "examples": {
                  "topClickedZeptoCodes": {
                    "value": {
                      "brand": "Zepto",
                      "referral_codes": [
                        {
                          "code": "https://zepto-prod.onelink.me/tC90/o9uykfz5",
                          "click_count": 446,
                          "updated_at": "2025-12-30T17:10:49.000000Z"
                        },
                        {
                          "code": "YIUNNT",
                          "click_count": 204,
                          "updated_at": "2026-03-03T07:40:07.000000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Store not found"
          }
        }
      }
    },
    "/referral/{store_slug}": {
      "get": {
        "operationId": "getReferralDetails",
        "summary": "Get referral details by store slug",
        "parameters": [
          {
            "name": "store_slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Referral details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralDetailsResponse"
                },
                "examples": {
                  "uberDetails": {
                    "value": {
                      "brand": "Uber",
                      "store_slug": "uber",
                      "bonus": "\u20b9200 ride credit",
                      "tagline": "Free rides for new users",
                      "description": "Ride booking offer details...",
                      "about": "Uber is a ride-hailing platform available in 70+ countries...",
                      "category": "ride-hailing",
                      "countries": [
                        "India",
                        "United States"
                      ],
                      "steps_to_redeem": "1. Copy a referral code \u2014 Pick a code below. 2. Download the Uber app \u2014 Sign up as a new user. 3. Apply the code \u2014 Enter it before your first ride.",
                      "how_it_works": [
                        {
                          "step": 1,
                          "title": "Copy a referral code",
                          "body": "Pick a code below."
                        },
                        {
                          "step": 2,
                          "title": "Download the Uber app",
                          "body": "Sign up as a new user."
                        }
                      ],
                      "key_features": [
                        {
                          "title": "Instant credit",
                          "body": "Bonus is applied right after your first ride."
                        }
                      ],
                      "faqs": [
                        {
                          "question": "When do I receive the bonus?",
                          "answer": "After completing your first ride with the code applied."
                        }
                      ],
                      "stats": [
                        {
                          "value": "\u20b9200",
                          "label": "Signup bonus"
                        }
                      ],
                      "referral_link": "https://m.uber.com/...",
                      "giverefer_page": "https://giverefer.com/store/uber",
                      "top_referral_codes": [
                        "UBER123",
                        "RIDE200",
                        "SAVE50",
                        "FASTRIDE",
                        "NEWUSER"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Store not found"
          }
        }
      }
    },
    "/popular-referrals": {
      "get": {
        "operationId": "getPopularReferrals",
        "summary": "Get popular referral programs",
        "responses": {
          "200": {
            "description": "Popular referral list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PopularReferralsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/stores/search": {
      "get": {
        "operationId": "searchStores",
        "summary": "Search stores by keyword",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StoreItem"
                  },
                  "maxItems": 50
                },
                "examples": {
                  "matches": {
                    "value": [
                      {
                        "brand": "Wise",
                        "slug": "wise",
                        "category": "money-transfer"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/popular": {
      "get": {
        "operationId": "getPopularStores",
        "summary": "Get popular stores",
        "responses": {
          "200": {
            "description": "Popular store list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PopularStoreItem"
                  },
                  "maxItems": 50
                },
                "examples": {
                  "popular": {
                    "value": [
                      {
                        "brand": "Uber",
                        "slug": "uber",
                        "category": "ride-hailing",
                        "views": 120340
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/trending": {
      "get": {
        "operationId": "getTrendingStores",
        "summary": "Get trending stores",
        "responses": {
          "200": {
            "description": "Trending store list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StoreItem"
                  },
                  "maxItems": 50
                },
                "examples": {
                  "trending": {
                    "value": [
                      {
                        "brand": "Zepto",
                        "slug": "zepto",
                        "category": "grocery-delivery",
                        "updated_at": "2026-03-12"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "getCategories",
        "summary": "Get referral store categories",
        "responses": {
          "200": {
            "description": "Category list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      },
                      "slug": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "slug"
                    ]
                  },
                  "maxItems": 100
                }
              }
            }
          }
        }
      }
    },
    "/countries": {
      "get": {
        "operationId": "getCountries",
        "summary": "Get supported countries",
        "responses": {
          "200": {
            "description": "Countries payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "short_name": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "short_name"
                        ]
                      },
                      "maxItems": 300
                    }
                  },
                  "required": [
                    "success",
                    "countries"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchReferralResponse": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string"
          },
          "store_slug": {
            "type": "string",
            "description": "Slug to use with the other referral endpoints."
          },
          "domain": {
            "type": "string",
            "nullable": true,
            "description": "The brand's own website domain, or null if not recorded."
          },
          "bonus": {
            "type": "string"
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ],
            "description": "Short marketing tagline for the offer."
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Category slug of the store."
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "brand",
          "store_slug",
          "bonus",
          "description",
          "url"
        ]
      },
      "SuggestReferralItem": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string"
          },
          "bonus": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "brand",
          "bonus",
          "url"
        ]
      },
      "ReferralDetailsResponse": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string"
          },
          "store_slug": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "nullable": true,
            "description": "The brand's own website domain, or null if not recorded."
          },
          "bonus": {
            "type": "string"
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ],
            "description": "Short marketing tagline for the offer."
          },
          "description": {
            "type": "string"
          },
          "about": {
            "type": [
              "string",
              "null"
            ],
            "description": "Longer about-the-brand text."
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Category slug of the store."
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Countries where the referral program is available. Empty when global or unspecified."
          },
          "steps_to_redeem": {
            "type": "string",
            "description": "Plain-text summary of the redemption steps."
          },
          "how_it_works": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HowItWorksStep"
            },
            "description": "Structured step-by-step redemption guide. Empty for stores without structured content."
          },
          "key_features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyFeature"
            },
            "description": "Key benefits of the referral program."
          },
          "faqs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FaqItem"
            },
            "description": "Frequently asked questions about the referral program."
          },
          "stats": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StatItem"
            },
            "description": "Headline stats such as bonus amount or user count."
          },
          "referral_link": {
            "type": "string"
          },
          "giverefer_page": {
            "type": "string",
            "format": "uri"
          },
          "top_referral_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "brand",
          "store_slug",
          "bonus",
          "description",
          "top_referral_codes",
          "steps_to_redeem",
          "referral_link",
          "giverefer_page"
        ]
      },
      "HowItWorksStep": {
        "type": "object",
        "properties": {
          "step": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "step",
          "title"
        ]
      },
      "KeyFeature": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "title"
        ]
      },
      "FaqItem": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        },
        "required": [
          "question",
          "answer"
        ]
      },
      "StatItem": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "value",
          "label"
        ]
      },
      "PopularReferralItem": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string"
          },
          "bonus": {
            "type": "string"
          },
          "store_slug": {
            "type": "string"
          },
          "giverefer_page": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "brand",
          "bonus",
          "store_slug",
          "giverefer_page"
        ]
      },
      "PopularReferralsResponse": {
        "type": "object",
        "properties": {
          "popular_referrals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PopularReferralItem"
            },
            "maxItems": 5
          }
        },
        "required": [
          "popular_referrals"
        ]
      },
      "ReferralCodeItem": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "click_count": {
            "type": "integer"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "code",
          "click_count",
          "updated_at"
        ]
      },
      "ReferralCodesResponse": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string"
          },
          "referral_codes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReferralCodeItem"
            },
            "maxItems": 5
          }
        },
        "required": [
          "brand",
          "referral_codes"
        ]
      },
      "StoreItem": {
        "type": "object",
        "properties": {
          "brand": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "brand",
          "slug",
          "category"
        ]
      },
      "PopularStoreItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StoreItem"
          },
          {
            "type": "object",
            "properties": {
              "views": {
                "type": "integer"
              }
            },
            "required": [
              "views"
            ]
          }
        ]
      }
    }
  }
}