"Detect" API Requests

To use the "Detect" API, your server will POST a HTTP request with your authorization key in an HTTP Auth Header, and a POST Body containing a JSON structure. The JSON you need to send to the API holds all the headers your visitor has sent. We decode and collate those headers, determining the browser and other system information your visitor is using, including if anything appears "fake", "weird", "dangerous" and so on, and very quickly return a well structured response to you.

How do "user agents" relate to all of this?

In the past, all you needed to do was to send your visitor's "user agent string" to the API and we could detect their browser, OS, device, and so on - just by using that. But now that Client Hints are being used by some browsers instead of/as well as user agents, you now need to send all their HTTP headers (one of which is their user agent).

If you really need to just parse user agent strings you can use the older "Version 2" of the WhatIsMyBrowser.com API. There is a dedicated endpoint for that. Version 2

Start by requesting all Client Hints from your visitors

To be able to use the Detect API at its full potential, you need to "ask" your visitor's web browsers to send your server all the Client Hints headers that it is capable of sending. The web browsers that send Client Hint headers will only send a few basic Client Hints by default, you have to specifically request that they send them all to your server.

To do that, your web server needs to include accept-ch and critical-ch HTTP response headers in page responses to your visitors, containing a comma seperated list of all the client hints headers you want them to send.

Thus, when your visitors send requests to your server, they will include all the possible Client Hints headers, that you can then send to the Detect API.

The list of Client Hint headers that should go in both of these HTTP Response Headers is:

Refer to the Sample Code for the way to do this in your preferred programming language.

Sending requests

Now that your website visitors are sending you all the Client Hints possible, you can gather all their HTTP Headers, including their User Agent, Client Hints, and any other headers, and send them to the Detect API.

You need to send a HTTP POST request to the Detect API end point URL, the POST body must be JSON that contains the HTTP headers of the visitor to your website that you wish to detect the requesting software/agent for.

HTTP POST Body

This is a sample HTTP POST Body, showing the JSON structure (it contains line breaks and indents for easier reading).

Your requests to the Detect API need to match this structure.

We have full sample code for using the Detect API. Please refer to it for full working examples.

Interpreting the API Response

When you send a request like this, the API will respond with a detailed JSON structure describing the agent and system that made the request.

Continue reading: The "Detect" API Responses.

Common questions

• "My visitors aren't sending any/enough/all Client Hints headers to my site"

  If you find that your website visitors aren't sending Client Hints headers to your site (and thus you aren't able to send them to the Detect end point), then the most likely explanations are:

  • You haven't included the necessary Client Hints reponse headers to your visitors. Browsers won't normally send every client hint to you unless you specifically request them. Follow our instructions to include the necessary HTTP Response headers, so that your visitors will send their Client Hints headers properly.
  • Your visitors aren't using a secure connection. Web browsers will only send Client Hints over TLS (HTTPS). If your visitors aren't using HTTPS on your site, then they won't transmit Client Hints.

  • Only Chromium based browsers support Client Hints. At the moment, only Chromium based browsers support Client Hints headers. If you look at the traffic for Firefox, Safari, and so on, you won't see any Client Hints headers from them. This is normal. Test your own website using Google Chrome and confirm that it is sending Client Hints headers to your site. Read: Which web browsers support Client Hints?

• "Why do the headers need to be sent in a list instead of a dictionary?"

  It indeed would have been possible for our API to simply accept the headers in your HTTP Body JSON as a straightforward dictionary - with the header name as the key, and the value of the HTTP header as the value of the dictionary. However the JSON specification makes no allowance for maintaining ordering in a dict, and the order of HTTP headers may one day be used as a further data point to help identify which browser/software is sending the requests - in particular to identify "real" verses "fake" traffic.

  So if your server was to send it's JSON request to our API, there would be no guarantee that the order we received them in your request would match how your server received the headers from your visitor.

  But since a JSON list does guarantee the order is preserved, the headers element must be a list of individual dictionaries, so that the order that your server received the headers is maintained when you send your API request to our "Detect" end point.

• "Do I have to include all HTTP headers of my visitors in the request to the API, or can I just send the User Agent and Client Hints headers?"

  We suggest including all the HTTP headers that your visitors send to you in your requests to our API, not just the User Agent and Client Hints headers.

  As of right now, we only perform analysis using the User Agent header and the various Client Hints headers, however in the future, we do plan to also analyse other HTTP headers that browsers send, even including ones like Accept, Accept-Language, and so on. The more data-points like this which are available to analyse the more accurate we can be in identifying fake requests.

  So even though we don't use all of them right now, to save having to revisit your code in the future, as well as having to worry about only sending the "right" headers, we suggest sending them all.

  Web browsers may start sending new Client Hints headers in the future, so if you are sending all the headers of your visitors, you won't have to update your code.

• What about the privacy & security considerations of sending my visitors HTTP headers

  We've thought about this a lot and are very conscious of problems it might introduce. We have taken care to prevent privacy and security issues.

  Firstly, except for a small handful of them, HTTP Headers are not generally considered "personally identifying information". There are a few HTTP Headers which do potentially carry sensitive information in them, and we redact their values before storing them.

  The values for any HTTP headers that contain "cookie", "auth", "csrf", or "referer" in the header name are redacted by our system before being stored, as otherwise this could inadvertently leak auth tokens. You are welcome to perform the same redacting on your end as well, but we don't want to create any security risks, so we take care to make sure that no kinds of authentication tokens are stored accidentally.