Migrate to the v1 API

This document shows you how to migrate from the v1beta1 version to the v1 version of the reCAPTCHA Enterprise API.

Starting June 2026, the v1beta1 endpoint will be progressively shut down. > During this phased shutdown, requests made to the v1beta1 endpoint from unmigrated services will begin to return errors.

To migrate your assessment calls from v1beta1 to v1, do the following:

  1. Replace calls to create assessments.

    Replace https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments?key=API_KEY with https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

  2. Understand the changes in the assessment's JSON response:

    When you use v1, the reasons and score fields are encapsulated in riskAnalysis in the response, and when you use v1beta1, thereasons and score fields are not encapsulated in the response.

    v1

    {
"event":{
  "expectedAction":"EXPECTED_ACTION",
  "hashedAccountId":"ACCOUNT_ID",
  "siteKey":"KEY_ID",
  "token":"TOKEN",
  "userAgent":"(USER-PROVIDED STRING)",
  "userIpAddress":"USER_PROVIDED_IP_ADDRESS"
},
"name":"ASSESSMENT_ID",
 "riskAnalysis":{
  "reasons":[],
  "score":"SCORE
},
"tokenProperties":{
  "action":"USER_INTERACTION",
  "createTime":"TIMESTAMP",
  "hostname":"HOSTNAME",
  "invalidReason":"(ENUM)",
  "valid":(BOOLEAN)
}
}

    v1beta1

    {
"event":{
  "expectedAction":"EXPECTED_ACTION",
  "hashedAccountId":"ACCOUNT_ID",
  "siteKey":"KEY_ID",
  "token":"TOKEN",
  "userAgent":"(USER-PROVIDED STRING)",
  "userIpAddress":"USER_PROVIDED_IP_ADDRESS"
},
"name":"ASSESSMENT_ID",
"reasons":[],
"score":"SCORE",

"tokenProperties":{
  "action":"USER_INTERACTION",
  "createTime":"TIMESTAMP",
  "hostname":"HOSTNAME",
  "invalidReason":"(ENUM)",
  "valid":(BOOLEAN)
}
}

  3. Update your environment to use the reasons and score fields from the JSON response for v1.

    The following sample code shows the fields that are used from the response of v1 and v1beta1:

    v1

    .....
.....
# Get the risk score and the reason(s)
for reason in response.risk_analysis.reasons:
    print(reason)
print(
    "The reCAPTCHA score for this token is: "
    + str(response.risk_analysis.score)
)
....
....

    v1beta1

    .....
.....
# Get the risk score and the reason(s)
for reason in response.reasons:
    print(reason)
print(
    "The reCAPTCHA score for this token is: "
    + str(response.score)
)
....
....

  4. Replace calls to annotate assessments.

    Replace https://recaptchaenterprise.googleapis.com/v1beta1/projects/PROJECT_ID/assessments}:annotate with https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments}:annotate

  5. If you are currently logging your create and annotate API calls using audit logging it is recommended to use platform logging (available for v1 only).

What's next