Required Headers

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

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

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 (end June 2026) to avoid rate-limiting and ensure proper traffic handling.

Frequently Asked Questions

Topic - Generic Questions on Headers

Question 1: What are the changes we need to do before adding this header code to our API calls?

The information listed below should be gathered before adding the code to your header:

X-HawkSearch-ClientGuid – This must be your own account’s Client GUID. This is available in HawkSearch Workbench-->Admin-->Setup Info

X-Forwarded-For – This should reflect the originating IP address of the end user. This value should not use the example value, but rather it needs to be dynamically set by your application.

User-Agent – This should also be updated to reflect the actual user agent of the request coming from your application, not the sample value shown in the article.

The values shown in the article are sample information provided for guidance only, so they should not be used as-is in a production implementation.

Reason: These headers improve our ability to distinguish legitimate traffic from unwanted traffic at the web application firewall level without having to process the request body.

For the most accurate values for X-Forwarded-For, User-Agent, and what it should contain, we recommend consulting with:

Your application’s Hosting Provider, or

Your internal IT / Development Team.

They’ll be able to confirm how these headers should be populated based on how your application handles requests with HawkSearch.

Lastly, we would recommend thorough testing when adding these headers to your LIVE site.

To test adding the headers, you can use Postman to validate the behavior before and after the changes. Here’s how:

Set up your API request in Postman

• Use the same endpoint, method (GET/POST), parameters, and body that your application uses.

Test without the new headers (baseline)

• Run the request without the updated headers.
• Save or note the response and result set.

Add the required headers

• Update the request headers in Postman with the respective values: ClientGuid, X-Forwarded-For, User-Agent
• Make sure these values match what your application will send.

Run the request again

• Execute the same query with the headers added.
• Compare the response to your baseline results.

Validate the outcome

• The result sets should be the same before and after adding the headers.
• Confirm there are no errors and that the request is processed successfully.

Using Postman in this way helps ensure the headers are correctly configured and that adding them does not negatively impact your API responses. If you notice any differences or errors, double-check the header values with your Hosted Vendor or IT team and/or contact us.

Question 2: Do these header changes apply only for certain HawkSearch API calls such as data/indexing or just customer-utilized APIs (search, recs, tracking)?

Answer: These header changes apply to all HawkSearch API calls.

• Indexing
• Dashboard
• Search
• Autocomplete
• Event tracking
• Recommendations

Topic - X-Forwarded-For:

Question 3: Our IP addresses are not fixed or static. What should we do? Wouldn’t this header be populated by Bridgeline’s load balancer? How should this be populated?

Answer:
If your IP addresses are not static, the X-Forwarded-For (XFF) header automatically manages this for you. As a request passes through proxies, each proxy appends the client’s current IP address to the XFF header, creating a list such as client_ip, proxy1_ip, proxy2_ip. The leftmost IP represents the original client’s IP, even if it changes over time.

Your application should read the first (leftmost) IP from the XFF header when the proxy is trusted. If the XFF header is not present or cannot be trusted, fall back to using the direct TCP connection’s REMOTE_ADDR, which will be the proxy’s IP address.

This isn’t generated by HawkSearch application load balancers and you would still need to send the IP address.

Question 4: On end-user machines (when making API calls via JavaScript) and on servers (when using the HawkSearch connector), does the X-Forwarded-For header need to be an IP address, or can we send a string like XYZ?

Answer:
The X-Forwarded-For header is expected to contain valid IP addresses. For example:

--header 'X-Forwarded-For: 203.0.113.45'

Sending arbitrary strings like XYZ is not supported and may cause the request to be ignored or rejected. The header is designed to track the client’s originating IP, so it should always reflect a valid IPv4 or IPv6 address.

Question 5: Wouldn’t the X-Forwarded-For header be populated by our load balancer? How should this be handled?###

Answer:
Yes, when your IP addresses are dynamic, the load balancer is responsible for populating the X-Forwarded-For (XFF) header automatically. You should not manually send this header, as the load balancer handles appending the client’s current IP to accurately track the originating IP.

The header will create a list of IPs (e.g., client_ip, proxy1_ip, proxy2_ip), with the leftmost IP representing the original client. Your application should read this first IP if the proxy is trusted. Otherwise, it can fall back to using the direct TCP connection’s REMOTE_ADDR.

Question 6: Where can I get X-forwarded to send?

Answer:

These headers are usually added by a proxy, load balancer, CDN, or reverse proxy (e.g., Nginx, AWS ALB, Cloudflare).

You normally do not generate them yourself unless you are acting as a proxy.

Example sources:

• Nginx / Apache
• AWS ALB / ELB
• Cloudflare, Fastly, etc.

Topic - User-agent:

Question 7: Can we send any value for the User-Agent header, or should we use one of the known common user-agent strings?

Answer:
You should send the User-Agent of the site visitor as-is

or

Please provide a user-agent that reflects the application being used. For example, if it runs on a system with a known user-agent, use that value. If it’s a custom system without a standard user-agent, use a descriptive identifier such as php6.5 or nginx3.2. As long as the User-Agent header includes something that clearly identifies the application, it will be acceptable.

If user agent is not sent, HawkSearch will use null or '-', which can have a negative impact managing bot traffic.

Reason:

This allows Bridgeline to identify and manage bot traffic.

Topic - Hawksearch connectors:

Question 8: When can we expect to have an updated Hawksearch connector available on NuGet for these requirements?

Answer: We will aim to have all the connectors updated by the end of March 2026. Instructions to implement these headers for platform integrations will be part of the release notes.

Topic - For AE Migrated Customers to Bridgeline’s Infrastructure

Question 9: We are following up on the email we received with the subject line “Action Required: HawkSearch API Hosting Updates”. Since we switched over from the American Eagle hosted HawkSearch servers to the AWS HawkSearch servers, are we already good with the requirements as laid out in the email? The URLs we currently use are formatted as such: https://enginename.api-na.hawksearch.com/

Answer:

If you are already switched over from the American Eagle hosted HawkSearch servers to the Bridgeline’s AWS HawkSearch servers, please check if you are sending us these information via headers even if you have switched over to using your Vanity URL

X-HawkSearch-ClientGuid – This must be your own account’s Client GUID. This info is available in HawkSearch Workbench-->Admin-->Setup Info

X-Forwarded-For – This should reflect the originating IP address of the end user. This value should not be left as the example; it needs to be dynamically set by your application.

User-Agent – This should also be updated to reflect the actual user agent of the request coming from your application, not the sample value shown in the article.

American Eagle Hosted HawkSearch clients can disregard the “Action Required: HawkSearch API Hosting Updates” email to take actions at this time as Bridgeline and American Eagle teams are currently migrating the clients to Bridgeline’s infrastructure. The necessary steps will be completed as part of the migration process.