openapi: 3.1.0
info:
  title: Friendly Captcha Siteverify API
  version: v2
  description: 'Best-effort OpenAPI 3.1 description of the Friendly Captcha v2 siteverify

    endpoint, which validates a Friendly Captcha solution token submitted with

    a protected form or API request.

    '
  contact:
    name: Friendly Captcha Developer Docs
    url: https://developer.friendlycaptcha.com/docs/v2/getting-started/verify
servers:
- url: https://global.frcapi.com
  description: Global endpoint
- url: https://eu.frcapi.com
  description: EU-hosted endpoint
security:
- apiKey: []
tags:
- name: Siteverify
paths:
  /api/v2/captcha/siteverify:
    post:
      tags:
      - Siteverify
      operationId: siteverify
      summary: Verify a Friendly Captcha response token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiteverifyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SiteverifyRequest'
      responses:
        '200':
          description: Verification performed (check the success field)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteverifyResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ErrorBody'
    ErrorBody:
      type: object
      properties:
        error_code:
          type: string
          description: Machine-readable error code (e.g. auth_required, auth_invalid, response_invalid, response_timeout, response_duplicate)
        detail:
          type: string
    SiteverifyResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the captcha solution was valid
        data:
          type: object
          properties:
            event_id:
              type: string
            challenge:
              type: object
              properties:
                timestamp:
                  type: string
                  format: date-time
                origin:
                  type: string
            risk_intelligence:
              type: object
              nullable: true
              additionalProperties: true
        error:
          $ref: '#/components/schemas/ErrorBody'
    SiteverifyRequest:
      type: object
      required:
      - response
      properties:
        response:
          type: string
          description: The response value submitted in the frc-captcha-response field
        sitekey:
          type: string
          description: Optional sitekey to verify the puzzle was issued for
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key created in the Friendly Captcha dashboard