> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a solve

> Creates a solve and reserves its price. Without `wait`, the initial response is normally 202. `wait` holds the request for 1–90 seconds; a completed solve is returned with 200, otherwise the open solve is returned with 202. Poll GET /solves/{id} to retrieve later results. Successful solves cost $0.00075; unsuccessful solves are not charged.

Create an hCaptcha token solve. A successful solve is charged against your prepaid balance.


## OpenAPI

````yaml https://ninetile.io/openapi.json POST /solves
openapi: 3.1.0
info:
  title: Ninetile API
  version: 1.0.0
  description: >-
    Native Ninetile JSON API. Solve hCaptcha challenges, retrieve solve status,
    report token outcomes, inspect account usage, and recognize hCaptcha image
    challenges. Successful solves and recognitions are charged to the account's
    prepaid USD balance.
servers:
  - url: https://api.ninetile.io/v1
    description: Primary API
  - url: https://api.radiumstore.org/v1
    description: Alternate API host
security:
  - BearerAuth: []
  - ApiKeyHeader: []
tags:
  - name: Solves
    description: Create, inspect, cancel, and report hCaptcha token solves.
  - name: Feedback
    description: Report verdicts for completed solves.
  - name: Account
    description: Inspect account balance, limits, and daily usage.
  - name: Recognition
    description: Recognize hCaptcha image challenges for clients running their own browser.
  - name: Status
    description: Public service liveness.
paths:
  /solves:
    post:
      tags:
        - Solves
      summary: Create an hCaptcha solve
      description: >-
        Creates a solve and reserves its price. Without `wait`, the initial
        response is normally 202. `wait` holds the request for 1–90 seconds; a
        completed solve is returned with 200, otherwise the open solve is
        returned with 202. Poll GET /solves/{id} to retrieve later results.
        Successful solves cost $0.00075; unsuccessful solves are not charged.
      operationId: createSolve
      parameters:
        - $ref: '#/components/parameters/Wait'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSolveRequest'
            example:
              type: hcaptcha
              sitekey: 00000000-0000-0000-0000-000000000000
              url: https://target.example/login
      responses:
        '200':
          description: Solve reached a final state while waiting.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Solve'
        '202':
          description: Solve is pending or solving; poll the solve resource.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Solve'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    Wait:
      name: wait
      in: query
      required: false
      description: >-
        Wait this many seconds for a final result (1–90). If omitted, return
        without waiting.
      schema:
        type: integer
        minimum: 1
        maximum: 90
  schemas:
    CreateSolveRequest:
      type: object
      required:
        - type
        - sitekey
        - url
      properties:
        type:
          $ref: '#/components/schemas/SolveType'
        sitekey:
          type: string
          format: uuid
          description: hCaptcha sitekey UUID.
        url:
          type: string
          format: uri
          pattern: ^https?://
          maxLength: 2048
          description: HTTP or HTTPS URL of the page containing the challenge.
        rqdata:
          type: string
          maxLength: 16384
          description: Fresh hCaptcha rqdata, when the page provides one.
        user_agent:
          type: string
          maxLength: 512
          description: >-
            Accepted but not applied. The solve response provides the user agent
            to use when submitting the token.
        proxy:
          $ref: '#/components/schemas/Proxy'
    Solve:
      type: object
      required:
        - id
        - object
        - type
        - status
        - sitekey
        - url
        - token
        - user_agent
        - error
        - charged_usd
        - proxy_bytes
        - created_at
        - started_at
        - finished_at
        - queue_ms
        - resolve_ms
        - warnings
      properties:
        id:
          type: string
          pattern: ^solve_
        object:
          const: solve
        type:
          $ref: '#/components/schemas/SolveType'
        status:
          $ref: '#/components/schemas/SolveStatus'
        sitekey:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        token:
          type:
            - string
            - 'null'
          description: >-
            hCaptcha response token when the solve succeeds; otherwise null.
            Token is cleared after 7 days.
        user_agent:
          type:
            - string
            - 'null'
        error:
          oneOf:
            - $ref: '#/components/schemas/SolveFailure'
            - type: 'null'
        charged_usd:
          type:
            - number
            - 'null'
          description: Final charge; null until the solve is final.
        proxy_bytes:
          type: 'null'
          description: Currently always null.
        created_at:
          type: string
          format: date-time
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        finished_at:
          type:
            - string
            - 'null'
          format: date-time
        queue_ms:
          type:
            - integer
            - 'null'
        resolve_ms:
          type:
            - integer
            - 'null'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/SolveWarning'
    SolveType:
      type: string
      enum:
        - hcaptcha
        - hcaptcha_enterprise
    Proxy:
      description: Optional public HTTP or HTTPS proxy. SOCKS proxies are not supported.
      oneOf:
        - type: string
          description: Proxy URL, e.g. `http://username:password@host:8080`.
        - $ref: '#/components/schemas/ProxyObject'
    SolveStatus:
      type: string
      enum:
        - pending
        - solving
        - solved
        - failed
        - cancelled
        - expired
    SolveFailure:
      type: object
      required:
        - code
        - message
        - reason
        - retryable
        - docs_url
      properties:
        code:
          type: string
          description: Solve failure code.
        message:
          type: string
        reason:
          type:
            - string
            - 'null'
        retryable:
          type: boolean
        docs_url:
          type:
            - string
            - 'null'
          format: uri
    SolveWarning:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - user_agent_not_applied
        message:
          type: string
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - param
            - request_id
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - unauthorized
                - insufficient_credits
                - key_credit_limit_exceeded
                - account_locked
                - forbidden
                - not_eligible
                - not_found
                - conflict
                - payload_too_large
                - unsupported_media_type
                - expired_window
                - recognition_failed
                - validation_error
                - concurrency_limit_exceeded
                - proxy_unavailable
                - rate_capped
                - rate_limited
                - sitekey_rate_limited
                - internal_error
                - maintenance
                - capacity_exhausted
                - proxy_pool_depleted
            message:
              type: string
            param:
              type:
                - string
                - 'null'
            request_id:
              type: string
              format: uuid
    ProxyObject:
      type: object
      required:
        - host
        - port
      properties:
        host:
          type: string
        port:
          oneOf:
            - type: integer
              minimum: 1
              maximum: 65535
            - type: string
              pattern: ^[0-9]{1,5}$
        scheme:
          type: string
          enum:
            - http
            - https
          default: http
        username:
          type: string
        password:
          type: string
          writeOnly: true
  headers:
    RequestId:
      description: Request identifier for support inquiries.
      schema:
        type: string
        format: uuid
    RetryAfter:
      description: >-
        Seconds to wait before retrying; present when the error asks the client
        to wait.
      schema:
        type: integer
        minimum: 1
  responses:
    BadRequest:
      description: Invalid JSON or a non-object request body (`invalid_request`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API key missing, malformed, unknown, or revoked (`unauthorized`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: >-
        Insufficient account balance or key spend limit (`insufficient_credits`,
        `key_credit_limit_exceeded`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        Account locked or key not permitted to access this endpoint
        (`account_locked`, `forbidden`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: >-
        Request body exceeds 12 MiB or an image exceeds 1.5 MiB
        (`payload_too_large`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Request body must use JSON content type (`unsupported_media_type`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: >-
        Field validation error or expired feedback window (`validation_error`,
        `expired_window`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        Request, concurrency, sitekey, or authentication-attempt limit reached
        (`rate_limited`, `concurrency_limit_exceeded`, `rate_capped`,
        `sitekey_rate_limited`, `proxy_unavailable`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected server error (`internal_error`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: >-
        Solver or recognition service is not ready or at capacity
        (`maintenance`, `capacity_exhausted`, `proxy_pool_depleted`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Ninetile API key, sent as `Authorization: Bearer <key>`. Keys are issued
        in the dashboard.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative to the Authorization Bearer header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.