Google reCAPTCHA Assessments API

openapi: 3.1.0
info:
  title: Google reCAPTCHA reCAPTCHA Enterprise Assessments API
  description: The reCAPTCHA Enterprise API provides bot detection and fraud prevention by creating assessments for user interaction tokens. It supports managing site keys, creating and annotating assessments, and configuring firewall policies.
  version: v1
  contact:
    name: Google Cloud Support
    url: https://cloud.google.com/recaptcha-enterprise/docs/support
  termsOfService: https://cloud.google.com/terms
servers:
- url: https://recaptchaenterprise.googleapis.com/v1
  description: reCAPTCHA Enterprise Production Server
security:
- oauth2: []
tags:
- name: Assessments
  description: Create and annotate risk assessments
paths:
  /projects/{projectId}/assessments:
    post:
      operationId: createAssessment
      summary: Google reCAPTCHA Create assessment
      description: Creates an assessment of a reCAPTCHA token. Returns a risk score between 0.0 and 1.0, reason codes, and token properties.
      tags:
      - Assessments
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Assessment'
      responses:
        '200':
          description: Assessment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assessment'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /projects/{projectId}/assessments/{assessmentId}:annotate:
    post:
      operationId: annotateAssessment
      summary: Google reCAPTCHA Annotate assessment
      description: Annotates an existing assessment with additional information to improve future risk analysis. Annotations provide feedback on whether the assessment was correct.
      tags:
      - Assessments
      parameters:
      - $ref: '#/components/parameters/projectId'
      - name: assessmentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                annotation:
                  type: string
                  enum:
                  - LEGITIMATE
                  - FRAUDULENT
                  - PASSWORD_CORRECT
                  - PASSWORD_INCORRECT
                reasons:
                  type: array
                  items:
                    type: string
                    enum:
                    - CHARGEBACK
                    - CHARGEBACK_FRAUD
                    - CHARGEBACK_DISPUTE
                    - PAYMENT_HEURISTICS
                    - INITIATED_TWO_FACTOR
                    - PASSED_TWO_FACTOR
                    - FAILED_TWO_FACTOR
                    - CORRECT_PASSWORD
                    - INCORRECT_PASSWORD
      responses:
        '200':
          description: Annotation recorded
components:
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      description: The Google Cloud project ID
      schema:
        type: string
  schemas:
    Assessment:
      type: object
      properties:
        name:
          type: string
          description: The resource name of the assessment
          readOnly: true
        event:
          type: object
          properties:
            token:
              type: string
              description: The reCAPTCHA token from the client
            siteKey:
              type: string
              description: The site key used to generate the token
            userAgent:
              type: string
            userIpAddress:
              type: string
            expectedAction:
              type: string
        riskAnalysis:
          type: object
          readOnly: true
          properties:
            score:
              type: number
              format: float
              description: Risk score from 0.0 (bot) to 1.0 (human)
              minimum: 0.0
              maximum: 1.0
            reasons:
              type: array
              items:
                type: string
                enum:
                - AUTOMATION
                - UNEXPECTED_ENVIRONMENT
                - TOO_MUCH_TRAFFIC
                - UNEXPECTED_USAGE_PATTERNS
                - LOW_CONFIDENCE_SCORE
        tokenProperties:
          type: object
          readOnly: true
          properties:
            valid:
              type: boolean
            hostname:
              type: string
            action:
              type: string
            createTime:
              type: string
              format: date-time
            invalidReason:
              type: string
              enum:
              - EXPIRED
              - DUPE
              - MISSING
              - BROWSER_ERROR
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/cloud-platform: Full access to Google Cloud
externalDocs:
  description: reCAPTCHA Enterprise REST API Reference
  url: https://cloud.google.com/recaptcha-enterprise/docs/reference/rest