Public API documentation

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 time.

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

Segregating by sitekey also may increase your earnings, as sitekeys with low traffic quality are penalized. In other words, if a bot is attacking one part of your site but not another, only one sitekey's traffic would be affected.

NOTE:

This API is currently considered Early Access and is subject to change at any time.

Getting your API key

To get an API key, you'll need to do this one of two ways

Go to the new Dashboard v2 and visit the settings page and see or regenerate your API Key. Be sure to use your API KEY not your account secret key.

Alternatively, visit this URL once logged into hcaptcha.com in your browser: https://hcaptcha.com/user/apikey

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.

To use it, simply append this API key to any of the endpoint URLs in this document like so: https://hcaptcha.com/dashboard/sitekey?api_key=[your-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://hcaptcha.com/user \
  -H "Authorization: Basic $(echo -n [your-api-key] | base64)"

Adding New Site Keys

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

Arguments:

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

Parameter Value Description
hostnames [ "host1.com", "host2.com" ] Optional. The hostnames where you will use this sitekey. All hostnames must resolve. Format: array of strings.
difficulty 1-4 Optional. The difficulty level for this sitekey. 1: Easy, 2: Moderate, 3: Difficult, 4: Always On. Defaults to 2. Format: integer 1-4.
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://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://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://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 Category Value
Business and industry 1
Cryptocurrencies 2
Games and entertainment 3
Family and relationships 4
Fitness and wellness 5
Food and drink 6
Hobbies and activities 7
News and current events 8
Shopping and fashion 9
Sports and outdoors 10
Technology 11

Fetching Statistics

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

Statistics API docs coming soon.