Required Headers

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.

All requests must also use a vanity URL; non-vanity URLs may be rate-limited after enforcement (expected by end of 2025 / March 2026).

Header	Purpose	Why it matters	Implementation	Example
X-HawkSearch-ClientGuid	Uniquely identifies your HawkSearch client (site or environment).	• Ensures requests are routed correctly to your configuration • Allows us to validate and personalize search traffic • Helps filter unauthorized or malformed requests at the edge (firewall/proxy).	• Must be included as an HTTP header • Overrides ClientGuid in the request body if both are present	`X-HawkSearch-ClientGuid: your-client-guid`
X-Forwarded-For	Captures the IP address of the end user (visitor), even when passing through proxies or load balancers.	• Supports geolocation, traffic auditing, and bot detection • Essential for identifying the actual visitor making the request	• Must be included as an HTTP header	`X-Forwarded-For: 203.0.113.45`
User-Agent	Provides details about the visitor's browser, device, or crawler.	• Helps distinguish bots from real users • Useful for analytics, profiling, and debugging	• Must be included as an HTTP header	`User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...`

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"
}'

⚠️ Important: All integrations must update to include these headers and use vanity URLs before enforcement (expected by end of 2025 / March 2026) to avoid rate-limiting and ensure proper traffic handling.