reCAPTCHA Enterprise API

openapi: 3.1.0
info:
  title: Google reCAPTCHA reCAPTCHA Enterprise 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
externalDocs:
  description: reCAPTCHA Enterprise REST API Reference
  url: https://cloud.google.com/recaptcha-enterprise/docs/reference/rest
servers:
  - url: https://recaptchaenterprise.googleapis.com/v1
    description: reCAPTCHA Enterprise Production Server
tags:
  - name: Assessments
    description: Create and annotate risk assessments
  - name: Keys
    description: Manage reCAPTCHA site keys
security:
  - oauth2: []
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
  /projects/{projectId}/keys:
    get:
      operationId: listKeys
      summary: Google reCAPTCHA List keys
      description: Lists all reCAPTCHA keys for the project.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/projectId'
        - name: pageSize
          in: query
          schema:
            type: integer
        - name: pageToken
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/Key'
                  nextPageToken:
                    type: string
    post:
      operationId: createKey
      summary: Google reCAPTCHA Create key
      description: Creates a new reCAPTCHA site key.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Key'
      responses:
        '200':
          description: Key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
  /projects/{projectId}/keys/{keyId}:
    get:
      operationId: getKey
      summary: Google reCAPTCHA Get key
      description: Retrieves the specified reCAPTCHA key.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/projectId'
        - name: keyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Key details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
    delete:
      operationId: deleteKey
      summary: Google reCAPTCHA Delete key
      description: Deletes the specified reCAPTCHA key.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/projectId'
        - name: keyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Key deleted
components:
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      description: The Google Cloud project ID
      schema:
        type: string
  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
  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]
    Key:
      type: object
      properties:
        name:
          type: string
          readOnly: true
        displayName:
          type: string
        webSettings:
          type: object
          properties:
            allowAllDomains:
              type: boolean
            allowedDomains:
              type: array
              items:
                type: string
            integrationType:
              type: string
              enum: [SCORE, CHECKBOX, INVISIBLE]
        androidSettings:
          type: object
          properties:
            allowAllPackageNames:
              type: boolean
            allowedPackageNames:
              type: array
              items:
                type: string
        iosSettings:
          type: object
          properties:
            allowAllBundleIds:
              type: boolean
            allowedBundleIds:
              type: array
              items:
                type: string
        labels:
          type: object
          additionalProperties:
            type: string
        createTime:
          type: string
          format: date-time
          readOnly: true