Capmonster Account API

openapi: 3.2.0
info:
  title: CapMonster Cloud API — createTask, getTaskResult &…
  version: 1.0.0
  summary: Task submission, polling results and balance for CapMonster Cloud.
  description: 'OpenAPI 3.1 specification for the core methods of the **public CapMonster Cloud API**: **`createTask`**, **`getTaskResult`** and **`getBalance`**.


    ## Flow

    1. Submit a captcha with **`POST /createTask`** → receive a `taskId`.

    2. Poll **`POST /getTaskResult`** with that `taskId` until `status` becomes `ready`,

    then read the `solution` (its shape depends on the captcha type).


    Check your account balance any time with **`POST /getBalance`**.


    ## Authentication

    There is **no header- or query-based auth**. Every request is authenticated by the

    `clientKey` field **inside the JSON request body** (your account API key from the

    dashboard). OpenAPI security schemes only cover

    header/query/cookie credentials, so `clientKey` is modelled as a required body property

    rather than a `securityScheme`.


    ## Error convention

    Every response carries an `errorId` (`0` = success, non-zero = failure). When `errorId != 0`,

    `errorCode` holds a machine-readable string (see `ErrorCode`) and `errorDescription` a human note.


    ## Notes & known gaps

    - Each captcha exposes a single `type` value (the one the public docs use). Legacy `...Proxyless`

    aliases are still accepted by the backend but are **not** documented here.

    - Field names are matched **case-insensitively** by the backend

    (e.g. `websiteURL` and `websiteUrl` are equivalent).

    - Each task links to the `getTaskResult` answer it yields via `x-solution` and its description,

    with a concrete `ready_` example under `getTaskResult`.'
  contact:
    name: CapMonster Cloud Support
    url: https://docs.capmonster.cloud/
  license:
    name: Proprietary
    url: https://capmonster.cloud/
servers:
- url: https://api.capmonster.cloud
  description: Primary API host
tags:
- name: Account
  description: Account-level operations.
paths:
  /getBalance:
    post:
      tags:
      - Account
      operationId: getBalance
      summary: Get account balance
      description: Returns the current credit balance of the account identified by `clientKey`.
      externalDocs:
        url: https://docs.capmonster.cloud/docs/api/methods/get-balance/
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBalanceRequest'
            examples:
              default:
                value:
                  clientKey: API_KEY
      responses:
        '200':
          description: Current balance, or an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalanceResponse'
              examples:
                success:
                  value:
                    errorId: 0
                    balance: 345.678
                error:
                  value:
                    errorId: 1
                    errorCode: ERROR_KEY_DOES_NOT_EXIST
                    errorDescription: Account authorization key not found in the system or has incorrect format
        '403':
          description: Invalid / unknown API key (`ERROR_KEY_DOES_NOT_EXIST`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalanceResponse'
              example:
                errorId: 1
                errorCode: ERROR_KEY_DOES_NOT_EXIST
                errorDescription: Account authorization key not found in the system or has incorrect format
components:
  schemas:
    ClientKey:
      type: string
      description: Your account API key (from https://dash.capmonster.cloud). Authenticates the request.
      examples:
      - API_KEY
    GetBalanceResponse:
      type: object
      required:
      - errorId
      properties:
        errorId:
          type: integer
          description: '`0` = success, non-zero = error.'
        errorCode:
          oneOf:
          - $ref: '#/components/schemas/ErrorCode'
          - type: 'null'
        errorDescription:
          type:
          - string
          - 'null'
        balance:
          type: number
          description: Available account balance (credits). Present on success.
          examples:
          - 345.678
    ErrorCode:
      type: string
      description: Machine-readable error code returned when `errorId` is non-zero.
      enum:
      - ERROR_KEY_DOES_NOT_EXIST
      - ERROR_ZERO_BALANCE
      - ERROR_TOO_BIG_CAPTCHA_FILESIZE
      - ERROR_ZERO_CAPTCHA_FILESIZE
      - ERROR_NO_SUCH_CAPCHA_ID
      - WRONG_CAPTCHA_ID
      - ERROR_CAPTCHA_UNSOLVABLE
      - CAPTCHA_NOT_READY
      - ERROR_IP_NOT_ALLOWED
      - ERROR_IP_BANNED
      - ERROR_NO_SUCH_METHOD
      - ERROR_TOO_MUCH_REQUESTS
      - ERROR_DOMAIN_NOT_ALLOWED
      - ERROR_TOKEN_EXPIRED
      - ERROR_NO_SLOT_AVAILABLE
      - ERROR_RECAPTCHA_INVALID_SITEKEY
      - ERROR_RECAPTCHA_INVALID_DOMAIN
      - ERROR_RECAPTCHA_TIMEOUT
      - ERROR_IP_BLOCKED
      - ERROR_PROXY_CONNECT_REFUSED
      - ERROR_PROXY_BANNED
      - ERROR_PROXY_MISSING
      - ERROR_PROXY_NOT_AUTHORISED
      - ERROR_PROXY_READ_TIMEOUT
      - ERROR_TASK_NOT_SUPPORTED
      - ERROR_TASK_ABSENT
      - ERROR_WRONG_USERAGENT
    GetBalanceRequest:
      type: object
      required:
      - clientKey
      properties:
        clientKey:
          $ref: '#/components/schemas/ClientKey'
      additionalProperties: false
externalDocs:
  description: Official CapMonster Cloud API documentation
  url: https://docs.capmonster.cloud/docs/category/api/