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.

Start setup View proof View examples

Runtime endpointhttps://edge.voidek.dev

Dashboard APIhttps://voidek.dev/api

Default formatJSON over HTTPS

Recommended timeout1.0-1.5s fail-open

Customer traffic uses the runtime endpoint. Dashboard, admin inbox, and account sessions use the first-party app API surface, so the protected site snippets can stay stable if management APIs move later.

Quickstart

Create an account, add one protected site, and run the first test decision.

Use this path when you arrive from crawler-defense guides and want to verify Voidek on a single protected route before enforcing blocks.

Create account

Open the dashboard and create a personal account.

Add protected site

Enter its domain and save the one-time runtime key as VOIDEK_API_KEY.

Run test decision

Copy the test request and compare the controlled GPTBot sample with live Analytics rows.

Enforce by route

Add middleware on protected routes after the first live row looks clean.

Public proof pageReview controlled sample replay for GPTBot, ClaudeBot, PerplexityBot, python requests, Playwright, and Googlebot.AI crawler blockerBlock GPTBot, ClaudeBot, PerplexityBot, and model-training crawlers without a WAF migration.Scraper protectionUse request scoring, browser signals, and middleware decisions against Python clients and automation.Bot protection APICall one runtime endpoint for allow, log, challenge, and block decisions at route boundaries.

Defense proof

Controlled decision proof demo.

Demo replay only. These rows are generated from Voidek sample requests and stay separate from live customer logs.

Open dashboard

Demo Voidek decisions for crawler and scraper request types
Client	Request	Decision	Why
GPTBotDemo replayAI crawler	`GET protected page`ai-crawler · high confidence	Blockedscore 100	Blocked because the user-agent matches a known AI crawler and arrives without normal browser navigation proof. ai-crawler · static-html-client · header-anomaly
ClaudeBotDemo replayAI crawler	`GET /docs`ai-crawler · high confidence	Blockedscore 100	Blocked because ClaudeBot is classified as model-training crawler traffic before protected content is served. ai-crawler · static-html-client · header-anomaly
PerplexityBotDemo replayAI crawler	`GET /docs`ai-crawler · high confidence	Blockedscore 100	Blocked because PerplexityBot is classified as AI crawler traffic before protected docs content is served. ai-crawler · static-html-client · header-anomaly
python-requestsDemo replayScraper library	`GET content endpoint`scraper · high confidence	Blockedscore 100	Blocked because a script client is making a high short-window request burst with no browser navigation headers. scraper-tooling · header-anomaly · rate-spike
Playwright / SeleniumDemo replayHeadless framework	`GET account route`scraper · high confidence	Blockedscore 100	Blocked because the request exposes automation tooling, webdriver, and a missing required browser challenge. scraper-tooling · static-html-client · header-anomaly
Masked Chromium runnerDemo replayHeadless challenge	`GET /account`browser-impersonation · medium confidence	Challengescore 75	Challenged because the client looks browser-like but lacks the headers a real navigation normally sends. browser-impersonation
GooglebotDemo replaySearch crawler	`GET /docs`search-engine · none confidence	Allowedscore 0	Allowed because known search-engine traffic is tagged separately from AI crawlers and scraper tooling. search-engine

Authentication

Use a bearer runtime key on server-side calls.

Keep the runtime 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 voidek-live-...
Content-Type: application/json

OpenAPI

Import the API into Swagger or Postman.

The OpenAPI file separates runtime bearer-key calls from dashboard session-cookie calls, so testing tools can show which endpoints need which credential.

Open /openapi.json in a new tab

Runtime API:
  Authorization: Bearer VOIDEK_API_KEY

Dashboard API:
  Cookie: vd_auth=...

Browser snippet:
  No secret key in client JavaScript

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://edge.voidek.dev/v1/decide", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Bearer " + process.env.VOIDEK_API_KEY
  },
  body: JSON.stringify({
    siteId: "SITE_ID",
    path: "protected page",
    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

POST /v1/decide parameters
Parameter	Type	Description
`siteId`	string	Required. Protected 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.

Response example

{
  "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

POST /v1/collect parameters
Parameter	Type	Description
`siteId`	string	Required. Protected 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`.

Response example

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

GET/v1/usage

Read monthly usage for quota and billing UI

GET /v1/usage parameters
Parameter	Type	Description
`siteId`	string	Required protected site ID query string parameter.
`period`	string	Current month is returned in `YYYY-MM` format.

Response example

{
  "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.

Create account

Use the dashboard to create a personal account before adding protected site configuration.

Add protected site and key

Enter the protected site domain, save the one-time runtime key as VOIDEK_API_KEY, and keep it server-side.

Run test decision

Copy the test request, run it from your terminal, and compare the controlled GPTBot sample with live Analytics rows.

Enforce by route

Add middleware on protected pages, docs, account routes, feeds, or API routes after live rows look clean.

Protection depth

Ready for protected site rollout, with a clear expansion roadmap.

Voidek covers your protected site rollout today. For broader paid plans, the next expansion areas are 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 plans scale

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

Later coverage

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.

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.

Runtime endpointhttps://edge.voidek.dev

Dashboard APIhttps://voidek.dev/api

Default formatJSON over HTTPS

Recommended timeout1.0-1.5s fail-open

Quickstart

Create an account, add one protected site, and run the first test decision.

Use this path when you arrive from crawler-defense guides and want to verify Voidek on a single protected route before enforcing blocks.

Create account

Open the dashboard and create a personal account.

Add protected site

Enter its domain and save the one-time runtime key as VOIDEK_API_KEY.

Run test decision

Copy the test request and compare the controlled GPTBot sample with live Analytics rows.

Enforce by route

Add middleware on protected routes after the first live row looks clean.

Demo Voidek decisions for crawler and scraper request types

Client

Request

Decision

Why

GPTBotDemo replayAI crawler

GET protected pageai-crawler · high confidence

Blockedscore 100

Blocked because the user-agent matches a known AI crawler and arrives without normal browser navigation proof.

ai-crawler · static-html-client · header-anomaly

ClaudeBotDemo replayAI crawler

GET /docsai-crawler · high confidence

Blockedscore 100

Blocked because ClaudeBot is classified as model-training crawler traffic before protected content is served.

ai-crawler · static-html-client · header-anomaly

PerplexityBotDemo replayAI crawler

GET /docsai-crawler · high confidence

Blockedscore 100

Blocked because PerplexityBot is classified as AI crawler traffic before protected docs content is served.

ai-crawler · static-html-client · header-anomaly

python-requestsDemo replayScraper library

GET content endpointscraper · high confidence

Blockedscore 100

Blocked because a script client is making a high short-window request burst with no browser navigation headers.

scraper-tooling · header-anomaly · rate-spike

Playwright / SeleniumDemo replayHeadless framework

GET account routescraper · high confidence

Blockedscore 100

Blocked because the request exposes automation tooling, webdriver, and a missing required browser challenge.

scraper-tooling · static-html-client · header-anomaly

Masked Chromium runnerDemo replayHeadless challenge

GET /accountbrowser-impersonation · medium confidence

Challengescore 75

Challenged because the client looks browser-like but lacks the headers a real navigation normally sends.

browser-impersonation

GooglebotDemo replaySearch crawler

GET /docssearch-engine · none confidence

Allowedscore 0

Allowed because known search-engine traffic is tagged separately from AI crawlers and scraper tooling.

search-engine

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

POST /v1/decide parameters

Parameter

Type

Description

siteId

string

Required. Protected 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.

POST /v1/collect parameters

Parameter

Type

Description

siteId

string

Required. Protected 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`.

GET /v1/usage parameters

Parameter

Type

Description

siteId

string

Required protected site ID query string parameter.

period

string

Current month is returned in `YYYY-MM` format.

Voidek API reference

Create an account, add one protected site, and run the first test decision.

Create account

Add protected site

Run test decision

Enforce by route

Controlled decision proof demo.

Use a bearer runtime key on server-side calls.

Import the API into Swagger or Postman.

Choose your stack.

Request, parameters, response.

Score one request before content is served

Store browser proof from the hosted snippet

Read monthly usage for quota and billing UI

Four decisions, one enforcement contract.

Move from visibility to blocking without hurting real users.

Ready for protected site rollout, with a clear expansion roadmap.

Ready now

Add before paid plans scale

Later coverage

Keep the product private, publish only install surfaces.

Loading Voidek quickstart

Voidek API reference

Create an account, add one protected site, and run the first test decision.

Create account

Add protected site

Run test decision

Enforce by route

Controlled decision proof demo.

Use a bearer runtime key on server-side calls.

Import the API into Swagger or Postman.

Choose your stack.

Request, parameters, response.

Score one request before content is served

Store browser proof from the hosted snippet

Read monthly usage for quota and billing UI

Four decisions, one enforcement contract.

Move from visibility to blocking without hurting real users.

Ready for protected site rollout, with a clear expansion roadmap.

Ready now

Add before paid plans scale

Later coverage

Keep the product private, publish only install surfaces.