To ensure optimal performance, security, and accurate request handling, all Search API requests to HawkSearch must include the following HTTP headers. These headers help us authenticate, route, and analyze traffic effectively, improving the search experience for everyone.

Required Headers

X-HawkSearch-ClientGuid

1. Purpose: Uniquely identifies your HawkSearch client (i.e., your site or environment).
2. Why it matters:
   1. Ensures requests are routed correctly to your configuration.
   2. Allows us to personalize and validate search traffic.
   3. Helps filter unauthorized or malformed requests at the edge (firewall/proxy).
3. Implementation:
   1. Must be included as an HTTP header.
   2. If both the header and request body contain a ClientGuid, the header will take precedence.

X-Forwarded-For

1. Purpose: Captures the IP address of the end user (visitors), even if the request passes through proxies or load balancers.
2. Why it matters:
   1. Supports geolocation, traffic auditing, and bot detection.
   2. Essential for identifying the actual visitor making the request.

User-Agent

1. Purpose: Provides details about the visitor's browser, device, or crawler.
2. Why it matters:
   1. Helps distinguish bots from real users.
   2. Useful for analytics, profiling, and debugging.

Example Search Request

curl --location 'https://searchapi-dev.hawksearch.net/api/v2/search' \
--header 'X-HawkSearch-ClientGuid: your client guid' \
--header 'X-Forwarded-For: 203.0.113.45' \
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/113.0.0.0' \
--header 'Content-Type: application/json' \
--data '{
    "Keyword": "jacket"
}'