One API Key

Build on API v2, with synchronous checks when needed

API v2 is the primary product for batch, multi-method, and automated detection. API v1 provides synchronous single-domain DNS Pollution checks for occasional requests that need a direct result. Both use the same account API Key.

Two complementary request models

Use API v2 for new integrations by default. Choose API v1 only for low-volume, single-domain checks that need a synchronous result.

Primary product · asynchronous batch

API v2 · Batch and multi-method automation

Use all seven detection methods. Query results with batch_id and check_id after creation for scalable workloads across cross-border networks.

Response model: Asynchronous batch
Best for: Batch detection, continuous automation, multi-node analysis
Detection scope: Seven methods and up to 1,000 targets per request

Quick start Open full API documentation

Synchronous · one domain

API v1 · Immediate, low-volume DNS Pollution checks

Check one domain and receive the DNS Pollution assessment in the same HTTP request, without creating a batch or polling for results.

Response model: Synchronous response
Best for: Troubleshooting, pre-launch validation, occasional automation
Detection scope: DNS Pollution only, one domain per request

Quick start Open full API documentation

API v2

API v2 quick start

This example creates an asynchronous GFW Full batch. A successful creation response means the task was accepted; query the batch or individual result endpoint for outcomes.

Base URL: https://api.weavebit.com/v2/
Authentication: Send the unified account API Key as an Authorization: Bearer header. The key identifies the user and is not tied to a detection method.

Open full API documentation View API Key

Minimal create request

curl -X POST 'https://api.weavebit.com/v2/task/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_REQUEST_ID' \
  -d '{
    "check_type": "gfw_full_domain_check",
    "target": [{"domain": "example.com"}],
    "nodes": ["cn-fj-zhangzhou-ct"]
  }'

Asynchronous create response

{
  "code": 0,
  "message": "ok",
  "batch_id": "...",
  "execution_deadline_at": "...Z",
  "expires_at": "...Z",
  "datas": [{"check_id": "...", "target": {"domain": "example.com"}}]
}

Basic API v2 flow

The batch lifecycle follows five clear steps, from node selection to retaining the required results.

1
Get nodes
Read the nodes currently available for detection.
2
Estimate cost
Optionally estimate the target and node combination.
3
Create batch
Receive a batch_id and a check_id for every target.
4
Query results
Read batch progress or an individual detection result.
5
Save data
Retain required results within 24 hours of creation.

API v2 batch rules

Review the execution, retention, and domain-normalization rules before submitting batch detection.

Request limit

Submit up to 1,000 targets per request.

Execution deadline

Each batch can execute for up to six hours. Unfinished items enter a final state after the deadline.

Privacy and retention

Batches and results are permanently deleted 24 hours after creation. Save any required data in time.

Internationalized domains

Inputs are normalized to lowercase ASCII Punycode. Creation and result responses return the normalized domain; use check_id for reliable matching.

API v1

API v1 quick start

API v1 provides synchronous, single-domain DNS Pollution checks. The request waits for detection and returns the assessment on the same connection.

Production URL: https://api.weavebit.com/v1/task/pollute
Authentication: Send key and host as application/x-www-form-urlencoded fields. POST is recommended so the API Key does not appear in URLs or access logs.

Where API v1 fits

TroubleshootingCheck one domain on demand without maintaining batch state.
Pre-launch validationRun a DNS Pollution check before publishing or switching a domain.
Occasional automationCheck one domain infrequently and process the returned result directly.

Usage boundary: Synchronous means the result is returned in the same HTTP request; it is not a fixed response-time guarantee. Clients must inspect error_code. result=0 means no pollution was detected, result=1 means pollution was detected, and result=-1 means no valid result is currently available. Use API v2 for batches, concurrent workloads, or other detection methods.

Open full API documentation API Explorer

Minimal synchronous request

curl -X POST 'https://api.weavebit.com/v1/task/pollute' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'host=example.com'

Synchronous detection response

{
  "error_code": 0,
  "error_msg": "Success",
  "result": 0
}

One API Key

One account, two request models

API v1 and API v2 share identity, balance, and customer tools, so choosing a request model does not require a second account.

Unified identity: The same account API Key works with API v1 and API v2.
Unified balance and usage: Charges use the same account balance and are visible together in Console.
Unified developer tools: Switch between both API documents and verify requests with API Explorer in Console.