Account Management and Metrics APIs (Enterprise)

note

These APIs are available to Enterprise users, along with features like passive ("No-CAPTCHA") modes, bot scores, custom threat models, and more. Details on hCaptcha Enterprise (BotStop) are available at BotStop.com.

Some features of your hCaptcha account can be programmatically managed. This includes creating new "site keys" to segregate traffic from different web properties or parts of the same site, e.g. login vs. signup.

You might want to do this in order to separately track how different sites you operate are doing, to change the difficulty level on particular parts of your site(s) to be appropriate for the interactions on that page, or to control your custom threat models on a granular basis.

Getting your API key#

To get an API key, you'll need to do the following:

Go to your dashboard and visit the settings page to get your API Key. Be sure to use your API KEY not your account secret key.

Authenticating against the API#

All of the endpoints described here are protected by an API key that you can obtain by following instructions in the section above.

For testing purposes, simply append this API key to any of the endpoint URLs in this document like so:

https://accounts.hcaptcha.com/dashboard/sitekey?api_key=[your-api-key]

However, in production you should use a header-based authentication method. We support two options. The first is to send the "x-api-key" header with your raw API key.

An alternative method to authenticate is to provide your API key via an authorization header in the format of Authorization: Basic [base64-encoded-apikey] like so:

curl https://accounts.hcaptcha.com/user \
-H "Authorization: Basic $(echo -n [your-api-key] | base64)"

Adding New Site Keys#

To add a new sitekey, POST to https://accounts.hcaptcha.com/dashboard/sitekey

Arguments#

The below arguments can be passed into the POST request body in JSON format

ParameterValueDescription
hostnames[ "host1.com", "host2.com" ]Optional. The hostnames where you will use this sitekey. All hostnames must resolve. Format: array of strings.
difficulty(integer)Optional. The difficulty level for this sitekey. 1: Easy, 2: Moderate, 3: Difficult, 4: Always On. Defaults to 2. Format: integer 1-N. Enterprise users: please see Understanding Scores and Modes for additional details.
interests[ 1, 2, 3 ]Optional. Set sitekey audience interests. May be used to filter captchas shown for relevance to audience. See Table of Interests below. Up to 3 values allowed. Format: array of integers..

Example (curl)#

curl https://accounts.hcaptcha.com/dashboard/sitekey?api_key=[your-api-key] \
-X POST \
-H 'content-type:application/json' \
-d '{"difficulty":3}'

Response#

You should receive a JSON response similar to the one below, including your new "sitekey" value.

{
"created": "Thu, 11 Jul 2019 19:30:01 GMT",
"difficulty": 3,
"hostnames": [],
"interests": [],
"sitekey": "dfa60f93-51ef-4703-a8fe-27aa9aff503e"
}

Updating an existing sitekey#

To update a field in an existing sitekey, perform a PATCH against

https://accounts.hcaptcha.com/dashboard/sitekey/[sitekey-id]

Arguments#

See the table above for the arguments that can be passed into this endpoint as the JSON body

Example (curl)#

curl https://accounts.hcaptcha.com/dashboard/sitekey/eb45f986-e13f-4ea6-bdde-504a5ddec1cb?api_key=[your-api-key] \
-X PATCH \
-H 'content-type:application/json' \
-d '{"difficulty":1}'

Response#

{
"difficulty": 1,
"hostnames": [],
"interests": [],
"sitekey": "eb45f986-e13f-4ea6-bdde-504a5ddec1cb"
}

Table of Interests#

You can specify up to three interests to help target hCaptchas shown to your visitors, referenced by their integer value in the table below.

Interest CategoryValue
Business and industry1
Cryptocurrencies2
Games and entertainment3
Family and relationships4
Fitness and wellness5
Food and drink6
Hobbies and activities7
News and current events8
Shopping and fashion9
Sports and outdoors10
Technology11

Fetching Statistics#

The statistics endpoints allow you to check how each of your sitekeys is doing.

To get real-time and timeseries data for a sitekey, GET:

https://accounts.hcaptcha.com/user/sitekey/[your-sitekey]/stats

Example (curl):#

curl https://accounts.hcaptcha.com/user/sitekey/[your-sitekey]/stats?api_key=[your-api-key]

Response:#

You should receive a JSON response similar to the one below, which may include daily, weekly, monthly, and yearly fields under the "timeseries" key depending on your sitekey's activity. This information can be up to 24 hours old. The "realtime" key contains the latest statistics.

If no activity at all has occurred, the endpoint will return only the "realtime" key.

{
"sitekey": "[your-sitekey]",
"realtime": {
"total_served": 0,
"total_solved": 0
},
"timeseries": {
"sitekey": "[your-sitekey]",
"timeseries": {
"daily": {
"2019-06-01": {
"diff": {
"served": 5.0,
"solved": 3.0
},
"total": {
"served": 5.0,
"solved": 3.0
}
},
"2019-06-02": {
"diff": {
"served": 0.0,
"solved": 0.0
},
"total": {
"served": 5.0,
"solved": 3.0
}
}
}
}
}
}
Note that additional fields may be included, depending on your Enterprise feature tier: please contact your integration support engineers for details.