{
  "openapi": "3.1.0",
  "info": {
    "title": "RaptorWayz API",
    "version": "1.0.0",
    "description": "Cloudflare-challenge-solving API. POST a domain and receive a valid cf_clearance cookie, a matching User-Agent, and a proxy on the same exit IP. Attach all three to your own request (cookie + User-Agent + proxy together) to load a Cloudflare-protected page. The proxy does no TLS interception, so RaptorWayz never sees your traffic.",
    "contact": { "name": "RaptorWayz support", "email": "support@raptorwayz.com", "url": "https://raptorwayz.com" },
    "license": { "name": "Proprietary" }
  },
  "servers": [{ "url": "https://raptorwayz.com", "description": "Production" }],
  "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
  "paths": {
    "/v1/solve": {
      "post": {
        "operationId": "solveCloudflare",
        "summary": "Solve a Cloudflare challenge for a domain",
        "description": "Returns a valid cf_clearance cookie, the matching User-Agent, and a proxy on the exit IP the cookie was solved on. Use all three together. Repeat calls for the same domain within the 25-minute window replay the same response (idempotent, no extra charge). Failed solves consume no quota.",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SolveRequest" },
              "example": { "domain": "example.com" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Solved (or the domain has no Cloudflare challenge). Two possible shapes.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/SolveResponse" },
                    { "$ref": "#/components/schemas/NoChallenge" }
                  ]
                }
              }
            }
          },
          "400": { "description": "Invalid domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "invalid_domain", "message": "Provide a valid domain, e.g. 'example.com'." } } } },
          "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "invalid_api_key", "message": "Unknown API key." } } } },
          "402": { "description": "Trial free calls used up (trial keys only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "trial_exhausted", "message": "Free trial calls used up. Purchase an API key to continue." } } } },
          "403": { "description": "API key disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "key_disabled", "message": "This API key is disabled." } } } },
          "429": { "description": "Rate limited, too many recent failed solves, or this key already solved a different domain this 25-min cycle (window_active). See Retry-After / seconds_until_next.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "window_active", "message": "This key already solved 'betplay.io' this cycle. You can solve a new domain in 900s, or add more keys to run domains in parallel.", "seconds_until_next": 900 } } } },
          "502": { "description": "Could not obtain a clearance. No quota consumed; retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "solve_failed", "message": "Could not obtain a Cloudflare clearance for example.com. No quota was consumed; retry shortly." } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key as a Bearer token: `Authorization: Bearer <API_KEY>`." },
      "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Alternatively pass the API key in the X-Api-Key header." }
    },
    "schemas": {
      "SolveRequest": {
        "type": "object",
        "required": ["domain"],
        "properties": {
          "domain": { "type": "string", "description": "The domain to solve, e.g. 'example.com' (no scheme).", "example": "example.com" }
        }
      },
      "SolveResponse": {
        "type": "object",
        "required": ["domain", "cf_clearance", "user_agent", "proxy", "expires_at", "seconds_until_next", "cached", "plan"],
        "properties": {
          "domain": { "type": "string" },
          "cf_clearance": { "type": "string", "description": "The Cloudflare clearance cookie. Send as Cookie: cf_clearance=<value>." },
          "user_agent": { "type": "string", "description": "The exact User-Agent the cookie was solved with. Must match on your requests." },
          "proxy": { "type": "string", "description": "Proxy URL on the exit IP the cookie is bound to. Route your requests through this.", "example": "http://<API_KEY>:x@raptorwayz.com:8080" },
          "expires_at": { "type": "integer", "format": "int64", "description": "Unix seconds when the cf_clearance cookie expires." },
          "seconds_until_next": { "type": "integer", "description": "Seconds until this key may solve a NEW domain again (the 25-minute window). 0 for trial keys." },
          "cached": { "type": "boolean", "description": "True when served from the idempotent window or warm cache (no fresh solve happened)." },
          "plan": { "type": "string", "enum": ["trial", "paid"] },
          "free_calls_remaining": { "type": ["integer", "null"], "description": "Remaining free trial calls (null for paid keys)." }
        }
      },
      "NoChallenge": {
        "type": "object",
        "required": ["status", "domain", "proxy", "message"],
        "properties": {
          "status": { "type": "string", "const": "no_challenge" },
          "domain": { "type": "string" },
          "proxy": { "type": "string" },
          "message": { "type": "string", "description": "The domain is reachable through the proxy with no Cloudflare challenge, so no cf_clearance cookie is needed." }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string", "description": "Stable machine-readable error code.", "enum": ["missing_api_key", "invalid_api_key", "key_disabled", "rate_limited", "too_many_failures", "window_active", "invalid_domain", "trial_exhausted", "solve_failed"] },
          "message": { "type": "string" },
          "seconds_until_next": { "type": ["integer", "null"], "description": "Set on cooldown/quota errors — how long to wait before retrying." }
        }
      }
    }
  }
}