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