API Docs

Voidek API reference

Add a browser snippet, call the decision API at your request boundary, and turn crawler pressure into explicit allow, log, challenge, or block actions.

Base URLhttps://api.gravitwave.com/voidek

Default formatJSON over HTTPS

Recommended timeout1.0-1.5s fail-open

Authentication

Use a bearer API key on server-side calls.

Keep the API key out of browser JavaScript. The public snippet uses only `data-site-id`; middleware and backend calls use `Authorization: Bearer VOIDEK_API_KEY`.

Authorization: Bearer vdk_live_...
Content-Type: application/json

Examples

Choose your stack.

Most API docs use stack tabs like JavaScript, Node.js, HTML, Python, and framework-specific examples. Voidek follows that pattern instead of a bulky dropdown.

const decision = await fetch("https://api.gravitwave.com/voidek/v1/decide", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Bearer " + process.env.VOIDEK_API_KEY
  },
  body: JSON.stringify({
    siteId: "SITE_ID",
    path: "/pricing",
    method: "GET",
    headers: Object.fromEntries(request.headers)
  })
}).then((response) => response.json());

Endpoints

Request, parameters, response.

Each endpoint is documented with the method/path, required parameters, and a representative JSON response so integration details are visible without hunting.

POST/v1/decide

Score one request before content is served

Parameter	Type	Description
`siteId`	string	Required. Site id from the dashboard.
`path`	string	Required. Path being protected.
`method`	string	GET, POST, PUT, DELETE, or another HTTP method.
`headers`	object	Raw request headers. Keep user-agent, accept, sec-fetch, client hints, and cookies.
`ip`	string	Best-effort client IP after your trusted proxy parsing.
`challengeToken`	string	Optional `vd_session` token produced by the browser snippet.

{
  "action": "block",
  "score": 100,
  "botType": "ai-crawler",
  "confidence": "high",
  "reasons": ["Known AI crawler user-agent"],
  "tags": ["ai-crawler", "automation"]
}

POST/v1/collect

Store browser proof from the hosted snippet

Parameter	Type	Description
`siteId`	string	Required. Site id embedded in the script tag.
`token`	string	Required. Short-lived browser challenge token.
`webdriver`	boolean	Navigator webdriver signal.
`language`	string	Browser language such as `en-US`.
`timezone`	string	Browser timezone such as `Asia/Seoul`.
`screen`	string	Screen fingerprint such as `1440x900x24`.

{
  "accepted": true,
  "challengePassed": true,
  "token": "vd.site_123...",
  "siteId": "site_123"
}

GET/v1/usage

Read monthly usage for quota and billing UI

Parameter	Type	Description
`siteId`	string	Required query string parameter.
`period`	string	Current month is returned in `YYYY-MM` format.

{
  "usage": {
    "siteId": "site_123",
    "plan": "free",
    "period": "2026-06",
    "used": 153,
    "quota": 1000,
    "remaining": 847
  }
}

Actions

Four decisions, one enforcement contract.

allowServe

Normal browser traffic and verified search engines.

logObserve

Suspicious but low-risk requests. Use this while tuning.

challengeVerify

Browser-like automation that needs proof before content returns.

blockReject

Known AI crawlers, scraper libraries, headless frameworks, path probes, and bursts.

Rollout checklist

Move from visibility to blocking without hurting real users.

Monitor

Install snippet and decision calls, but keep public pages fail-open while you baseline normal traffic.

Challenge

Apply to ambiguous browser-like traffic on content pages where false positives would be expensive.

Block

Use for GPTBot, ClaudeBot, PerplexityBot, python clients, Selenium, Playwright, credential probes, and high-rate bursts.

Measure

Watch `x-voidek-action`, `x-voidek-score`, request logs, 5xx, latency, and monthly quota.

Protection depth

Serviceable for beta, with a clear moat roadmap.

Voidek is strong enough for owned-site beta protection today. For broader paid launch, the next moat is better tuning, customer controls, and richer network reputation.

Ready now

AI crawler lists, scraper user agents, browser automation headers, webdriver signals, challenge token checks, path scan scoring, and burst pressure.

Add before paid launch

Managed allowlists, branded challenge pages, per-site rules, usage aggregation tables, webhook alerts, and trusted proxy configuration UI.

Later moat

IP reputation feeds, ASN/datacenter scoring, JA3/TLS fingerprints, behavioral replay, robots policy comparison, and customer-tuned model thresholds.

Public libraries

Keep the product private, publish only install surfaces.

@voidek/nodeExpress, NestJS, and Fastify middleware surface.

@voidek/nextProxy helpers and safe header forwarding utilities.

@voidek/browserSnippet loader configuration and typed browser payloads.

voidek-examplesPublic examples for Next.js, Node.js, Python, and edge workers.