Required Headers & Vanity URL Enforcement (Effective June 2026)
In an effort to improve security, performance, and traffic management, all HawkSearch API requests must include the following headers and use a vanity URL. Requests missing these headers or using non-vanity URLs may be rate-limited after June 2026.
Required Headers
| 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)... |
Search API Behavior
- If
X-HawkSearch-ClientGuidis present in the header, it overrides anyClientGuidvalue in the request body. - Requests containing only the body value are temporarily accepted for backward compatibility.
- Enforcement requiring headers and vanity URLs is expected by July 2026.
Example Request
curl --location 'https://searchapi-dev.hawksearch.net/api/v2/search' \
--header 'X-HawkSearch-ClientGuid: f51060e1c38446f0bacdf283390c37e8' \
--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 should update to include these headers and use vanity URLs before the enforcement date to avoid traffic rate limiting and ensure proper firewall filtering.