openapi: 3.1.0
info:
  title: Lemin Captcha Verification API
  version: v1
  summary: Server-side verification of Lemin gamified (cropped) CAPTCHA answers.
  description: The Lemin Captcha (Capy Inc.) verification API. After a website visitor completes a Lemin gamified puzzle CAPTCHA in the browser, the front end receives an encrypted `answer` and a `challenge_id`. The site's back end submits those, together with its account `private_key`, to this endpoint to confirm the puzzle was solved by a human before trusting the request. Verification must be performed server-side so the `private_key` is never exposed to the client. This description was generated by the API Evangelist enrichment pipeline from Lemin's public developer documentation (https://help.leminnow.com/knowledge/developers-guide); Lemin does not publish an OpenAPI definition.
  contact:
    name: Lemin / Capy Inc.
    url: https://help.leminnow.com/knowledge/developers-guide
  x-apievangelist-generated: true
servers:
- url: https://api.leminnow.com
  description: Lemin Captcha production API
tags:
- name: Verification
  description: Server-side CAPTCHA answer verification.
paths:
  /captcha/v1/cropped/validate:
    post:
      operationId: validateCroppedCaptcha
      summary: Verify a Lemin cropped-captcha answer
      description: Validate the encrypted answer a visitor produced for a Lemin cropped (gamified puzzle) CAPTCHA challenge. Call this from your back end only; the `private_key` must never be sent from the browser. The endpoint always responds with HTTP 200 and a JSON body whose `success` boolean carries the verification outcome; failures include a machine-readable `code` and human-readable `message`.
      tags:
      - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateRequest'
            examples:
              default:
                summary: Verification request
                value:
                  private_key: f902f944-7009-4764-97a3-c7bab9b5fe85
                  challenge_id: 854374ce-99d7-4721-81f4-8acfc460356d
                  answer: 0xax76x0xax6sx0x0x6sx0x0x6ix0x0x68x0x0x5ux0x0x5kx0xax5kx0xax5ax0xax50x0xax4mx0xax4cx
      responses:
        '200':
          description: Verification result. Returned for both successful and failed verifications; inspect the `success` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateResponse'
              examples:
                success:
                  summary: Answer accepted
                  value:
                    success: true
                    message: null
                    code: null
                incorrect_answer:
                  summary: Answer rejected
                  value:
                    success: false
                    message: Incorrect Answer
                    code: incorrect_answer
                invalid_private_key:
                  summary: Bad account key
                  value:
                    success: false
                    message: Invalid private_key
                    code: invalid_private_key
components:
  schemas:
    ValidateRequest:
      type: object
      required:
      - private_key
      - challenge_id
      - answer
      properties:
        private_key:
          type: string
          format: uuid
          description: Your account verification (secret) key from the Lemin Dashboard. Server-side only — never expose to the browser.
        challenge_id:
          type: string
          format: uuid
          description: Identifier for the specific CAPTCHA challenge instance the visitor solved.
        answer:
          type: string
          description: The encrypted visitor response returned by the client-side widget.
    ValidateResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the CAPTCHA answer verified successfully.
        message:
          type:
          - string
          - 'null'
          description: Human-readable description of the failure, or null on success.
        code:
          type:
          - string
          - 'null'
          description: Machine-readable failure identifier, or null on success. One of incorrect_answer, invalid_parameters, invalid_challenge_id, invalid_private_key, challenge_is_not_active, invalid_cropped_captcha.
          enum:
          - incorrect_answer
          - invalid_parameters
          - invalid_challenge_id
          - invalid_private_key
          - challenge_is_not_active
          - invalid_cropped_captcha
          - null