PrivateCaptcha/docs/openapi.yaml

openapi: 3.0.4
info:
  title: Private Captcha - OpenAPI 3.0
  description: |-
    Private Captcha is an independent, privacy-first, self-hostable Proof-of-Work CAPTCHA service made in EU.
    Instead of asking users to solve complex puzzles or track their behavior, Private Captcha solves an invisible cryptographic task in the background. The system automatically adjusts the task difficulty, ensuring smooth access for real users while making it too costly for bots to attempt. Cryptographic task provides equal security regardless of bot's intelligence level, making it effective even as AI technology improves.

    Some useful links:
    - [Private Captcha repository](https://github.com/PrivateCaptcha/PrivateCaptcha)
    - [Official Documentation](https://docs.privatecaptcha.com)
  termsOfService: https://privatecaptcha.com/legal/terms-and-conditions/
  contact:
    email: hello@privatecaptcha.com
  license:
    name: PolyForm Noncommercial License 1.0.0
    url: https://polyformproject.org/licenses/noncommercial/1.0.0
  version: 1.0.0
externalDocs:
  description: Find out more about Private Captcha
  url: https://privatecaptcha.com
servers:
  - url: https://api.privatecaptcha.com
  - url: https://api.eu.privatecaptcha.com
tags:
  - name: puzzle
    description: Fetch Puzzle for client widget
  - name: verify
    description: Verify puzzle solutions
    externalDocs:
      description: Find out more about Verify API
      url: https://docs.privatecaptcha.com/docs/reference/verify-api/
paths:
  /puzzle:
    get:
      tags:
        - puzzle
      summary: Retrieve a new puzzle
      description: Returns a unique serialized signed puzzle for the widget
      operationId: get-puzzle
      parameters:
        - name: sitekey
          in: query
          description: Property id for which the puzzle is requested
          required: true
          schema:
            type: string
          example: "aaaaaaaabbbbccccddddeeeeeeeeeeee"
        - name: Origin
          in: header
          description: Domain that corresponds to the Property sitekey
          schema:
            type: string
          example: "example.com"
      responses:
        "200":
          description: Puzzle created
          content:
            text/plain:
              schema:
                type: string
              example: "Aaqqqqq7u8zM3d3u7u7u7u4AAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAA=.AQCiRYnFLBXoqfEYUz7Up+ktTXhxXgw="
          headers:
            X-Rate-Limit:
              description: calls per second allowed to the user
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: number of operations remaining in the given time slot
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: number of seconds until rate limit is reset
              schema:
                type: integer
                format: int32
            Retry-After:
              description: recommended number of seconds to wait until retrying
              schema:
                type: integer
                format: int32
        "400":
          description: Invalid sitekey value or Origin header is missing
        "403":
          description: Sitekey does not exist, Origin does not correspond to property
        "429":
          description: Rate limited
        "500":
          description: Unexpected internal error
  /verify:
    post:
      tags:
        - verify
      summary: Verify puzzle solution (official API)
      description: API to verify form field with client solution used by SDKs and API clients
      operationId: post-verify
      requestBody:
        description: Solution
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyResponse"
          headers:
            X-Rate-Limit:
              description: calls per second allowed to the API key
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: number of operations remaining in the given time slot
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: number of seconds until rate limit is reset
              schema:
                type: integer
                format: int32
            Retry-After:
              description: recommended number of seconds to wait until retrying
              schema:
                type: integer
                format: int32
        "400":
          description: Invalid API key format
        "403":
          description: API key not found
        "429":
          description: API key rate limited
      security:
        - ApiKeyAuth: []
  /siteverify:
    post:
      tags:
        - verify
      summary: Verify puzzle solution (reCAPCHA-compatible)
      description: reCAPCHA-compatible API to verify form field with client solution
      operationId: post-siteverify
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                secret:
                  description: API key (auth)
                  type: string
                response:
                  description: Solution of the solved captcha
                  type: string
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteVerifyResponse"
          headers:
            X-Rate-Limit:
              description: calls per second allowed to the API key
              schema:
                type: integer
                format: int32
            X-RateLimit-Remaining:
              description: number of operations remaining in the given time slot
              schema:
                type: integer
                format: int32
            X-RateLimit-Reset:
              description: number of seconds until rate limit is reset
              schema:
                type: integer
                format: int32
            Retry-After:
              description: recommended number of seconds to wait until retrying
              schema:
                type: integer
                format: int32
        "400":
          description: Invalid API key format
        "403":
          description: API key not found
        "429":
          description: API key rate limited

components:
  schemas:
    SiteVerifyResponse:
      type: object
      required:
        - success
        - error-codes
        - challenge_ts
        - hostname
      properties:
        success:
          type: boolean
        error-codes:
          type: array
          items:
            $ref: "#/components/schemas/VerifyErrorCode"
        hostname:
          type: string
          example: example.com
        challenge_ts:
          type: string
          format: date-time
          example: "2009-11-10T23:00:00Z"
        score:
          type: number
        action:
          type: string
    VerifyErrorCode:
      type: string
      enum:
        - no-error
        - error-other
        - solution-duplicates
        - solution-invalid
        - solution-bad-format
        - puzzle-expired
        - property-invalid
        - property-owner-mismatch
        - solution-verified-before
        - property-test
        - maintenance-mode
        - integrity-error
    VerifyResponse:
      type: object
      required:
        - success
        - code
        - timestamp
        - origin
      properties:
        success:
          type: boolean
        code:
          type: number
        origin:
          type: string
          example: example.com
        timestamp:
          type: string
          format: date-time
          example: "2009-11-10T23:00:00Z"
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key