Search BlackHatWorld Discussions

POST/v1/blackhatworld/search

Find public discussions and return titles, links, snippets, result types, and author and forum details when available. Set title_only to search titles only. Query spelling is preserved; no automatic spelling correction is applied. A Post result is a matching reply within the titled discussion. Titles and snippets preserve words and punctuation while normalizing whitespace. Request 1-50 pages (not a result count), or continue a search using the returned search_id, the same query, and a starting page. Pagination reports the pages retrieved and why retrieval stopped; results may not include all matching discussions. Pass a returned results[].url to POST /v1/fetch to read the discussion content. No BlackHatWorld account is required. A completed search costs 10 Credits plus 1 Credit per returned result; failed searches are not charged. Reuse the same Idempotency-Key when retrying the same request. No matches returns blackhatworld_no_results; for blackhatworld_search_failed, check the error's retryable field.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com

curl -X POST "https://kieapi.com/v1/blackhatworld/search" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "query": "<value>"
}'

Authentication

BearerAuth

Parameters

Idempotency-Key header · string: Caller-generated key, up to 128 characters, that identifies one API Market write and its billing event. Reuse the same key only when retrying the same logical request. Replays do not create another reservation or capture.

Request body required

application/json

BlackHatWorldSearchRequest

query string required
search_id string | null
page integer: Default: 1
pages integer: Default: 1
delay number: Seconds between result pages. This wait counts toward the call's execution time limit; insufficient time fails the call instead of returning partial success.
Default: 1
timeout number: Default: 30
retries integer: Maximum additional attempts for recoverable failures. An accepted or uncertain search submission is not repeated.
Default: 2
impersonate string: Default: "chrome131"
title_only boolean: Default: false

Responses

200 Search results and pagination details.

application/json

BlackHatWorldSearchResponse

source object required
query string required
search_id string required
pagination object required
result_count integer required
results array of object required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

402 The Team does not have enough available Credits for the maximum reservation.

application/json

PublicErrorResponse

error PublicError required

404 BlackHatWorld accepted the search but returned no results.

application/json

PublicErrorResponse

error PublicError required

409 Billing settlement requires reconciliation, or the idempotency key was reused for a different logical request.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

application/json

PublicErrorResponse

error PublicError required

502 Upstream fetch or network failure.

application/json

PublicErrorResponse

error PublicError required

503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

BlackHatWorldSearchRequest

object

query string required
search_id string | null
page integer: Default: 1
pages integer: Default: 1
delay number: Seconds between result pages. This wait counts toward the call's execution time limit; insufficient time fails the call instead of returning partial success.
Default: 1
timeout number: Default: 30
retries integer: Maximum additional attempts for recoverable failures. An accepted or uncertain search submission is not repeated.
Default: 2
impersonate string: Default: "chrome131"
title_only boolean: Default: false

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "search_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]+$"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "pages": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 1
    },
    "delay": {
      "type": "number",
      "minimum": 0,
      "maximum": 60,
      "default": 1,
      "description": "Seconds between result pages. This wait counts toward the call's execution time limit; insufficient time fails the call instead of returning partial success."
    },
    "timeout": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 60,
      "default": 30
    },
    "retries": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5,
      "default": 2,
      "description": "Maximum additional attempts for recoverable failures. An accepted or uncertain search submission is not repeated."
    },
    "impersonate": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "default": "chrome131"
    },
    "title_only": {
      "type": "boolean",
      "default": false
    }
  }
}

BlackHatWorldSearchResponse

object

source object required
query string required
search_id string required
pagination object required
result_count integer required
results array of object required

Complete schema

{
  "type": "object",
  "required": [
    "source",
    "query",
    "search_id",
    "pagination",
    "result_count",
    "results"
  ],
  "properties": {
    "source": {
      "type": "object",
      "properties": {
        "base_url": {
          "type": "string"
        },
        "transport": {
          "type": "string",
          "enum": [
            "curl_cffi"
          ]
        },
        "impersonate": {
          "type": [
            "string",
            "null"
          ]
        },
        "browser_used": {
          "type": "boolean",
          "description": "Whether this search used browser admission before HTTP business requests."
        },
        "bootstrap_used": {
          "type": "boolean"
        },
        "pagination_cookie_sent": {
          "type": "boolean",
          "description": "Whether page GETs sent server-managed clearance."
        },
        "clearance_reused": {
          "type": "boolean",
          "description": "Whether this call reused cached anonymous admission."
        }
      }
    },
    "query": {
      "type": "string"
    },
    "search_id": {
      "type": "string"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "start_page": {
          "type": "integer"
        },
        "requested_pages": {
          "type": "integer"
        },
        "fetched_pages": {
          "type": "integer"
        },
        "stopped_reason": {
          "type": "string",
          "enum": [
            "requested_page_limit",
            "last_page",
            "no_results"
          ]
        },
        "pages": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "result_count": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "url",
          "snippet",
          "result_type"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Discussion or media title with words and punctuation preserved and whitespace normalized."
          },
          "url": {
            "type": "string"
          },
          "snippet": {
            "type": "string",
            "description": "Matching content excerpt with words and punctuation preserved and whitespace normalized."
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          },
          "result_type": {
            "type": "string",
            "enum": [
              "Thread",
              "Post",
              "Media"
            ],
            "description": "Post identifies a matching reply within the titled discussion."
          },
          "datetime": {
            "type": [
              "string",
              "null"
            ]
          },
          "date": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "replies": {
            "type": [
              "integer",
              "null"
            ]
          },
          "forum": {
            "type": [
              "string",
              "null"
            ]
          },
          "forum_url": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}

PublicErrorResponse

object

error PublicError required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required: Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"
message string required
type string required: Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"
retryable boolean required
request_id string | null
details object

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}