openapi: 3.0.3
info:
  title: reCAPTCHA v2
  version: ""
  description: >
    Google's “I'm not a robot” CAPTCHA that may include checkboxes or image/audio challenges. CaptchaAI returns a valid token for site verification.
servers:
  - url: https://ocr.captchaai.com/

paths:
  /in.php:
    post:
      operationId: submit-task
      summary: Submit Task
      description: >
        Send `method=userrecaptcha` with googlekey and pageurl to POST /in.php. Returns a Task ID.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/RecaptchaV2Payload"
            examples:
              minimal:
                summary: Minimal submission
                value:
                  key: YOUR_API_KEY
                  method: userrecaptcha
                  googlekey: "6Le-...sitekey..."
                  pageurl: "https://example.com/page"
              withProxy:
                summary: With proxy and User-Agent
                value:
                  key: YOUR_API_KEY
                  method: userrecaptcha
                  googlekey: "6Le-...sitekey..."
                  pageurl: "https://example.com/page"
                  proxy: "user:pass@123.123.123.123:3128"
                  proxytype: HTTP
                  userAgent: "Mozilla/5.0 ..."
      responses:
        '200':
          description: Submission accepted — returns task ID
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SubmitOkText'
              examples:
                ok:
                  value: "OK|0123456789"
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitOkJson'

  /res.php:
    post:
      operationId: get-result
      summary: Get Result
      description: >
        Poll POST /res.php with the Task ID to obtain the reCAPTCHA response token.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [key, action, id]
              properties:
                key:
                  type: string
                  description: Your API key (32 characters)
                action:
                  type: string
                  enum: [get]
                  description: Must be `get`
                id:
                  type: string
                  description: Task ID returned by /in.php
                json:
                  type: integer
                  enum: [0, 1]
                  default: 0
                  description: >-
                    0 - plain text response.<br/>
                    1 - JSON response.
            examples:
              poll:
                summary: Poll for result
                value:
                  key: YOUR_API_KEY
                  action: get
                  id: "0123456789"
      responses:
        "200":
          description: Result, not-ready notice, or error code
          content:
            text/plain:
              schema:
                type: string
              examples:
                ok:
                  value: "OK|TOKEN_OR_TEXT"
                notReady:
                  value: "CAPCHA_NOT_READY"
            application/json:
              schema:
                $ref: '#/components/schemas/ResOkJson'
              examples:
                ok:
                  summary: Solved
                  value:
                    status: 1
                    request: "TOKEN_OR_TEXT"
                notReady:
                  summary: Not ready yet
                  value:
                    status: 0
                    request: "CAPCHA_NOT_READY"

components:
  schemas:
    RecaptchaV2Payload:
      type: object
      required: [key, method, googlekey, pageurl]
      properties:
        key:
          type: string
          description: Your API key (32 characters)
        method:
          type: string
          enum: [userrecaptcha]
        googlekey:
          type: string
          description: Sitekey from the page (data-sitekey or iframe k=)
        pageurl:
          type: string
          format: url
          description: Full URL where reCAPTCHA appears
        domain:
          type: string
          description: "Domain used to load the captcha: google.com or recaptcha.net"
          default: "google.com"
        invisible:
          type: integer
          enum: [0, 1]
          default: 0
          description: >-
            1 - means that reCAPTCHA is invisible.<br/>
            0 - normal reCAPTCHA.
        data-s:
          type: string
          description: Value of `data-s`.  Currently applicable for Google Search and other Google services.
        userAgent:
          type: string
          description: User-Agent string passed to the solver browser
        cookies:
          type: string
          description: >-
            Your cookies will be passed to the solver browser.<br/>
            Format: `KEY1:Value1;KEY2:Value2;` [Learn More](/guides/cookies)
        proxy:
          type: string
          description: >-
            Format: `login:password@123.123.123.123:3128`.<br/>
            [Learn More](/guides/proxy)
        proxytype:
          type: string
          description: 'Type of your proxy: `HTTP`, `HTTPS`, `SOCKS4`, `SOCKS5`.'
        json:
          type: integer
          enum: [0, 1]
          default: 0
          description: >-
            0 - plain text response.<br/>
            1 - JSON response.

    SubmitOkJson:
      type: object
      properties:
        status:
          type: integer
          example: 1
        request:
          type: string
          example: "0123456789"

    SubmitOkText:
      type: string
      description: Plain-text submission response.
      example: "OK|0123456789"

    ResOkJson:
      type: object
      properties:
        status:
          type: integer
          enum: [1]
          example: 1
        request:
          type: string
          description: Token on success, or an error code
          example: "TOKEN_OR_TEXT"
