Skip to content
WebDecoy Docs

API Reference Summary

Quick reference for key WebDecoy API endpoints.

Overview

Section titled “Overview”

The WebDecoy API uses REST architecture with JSON payloads. All endpoints require authentication via Bearer token (API key or Auth0 JWT).

Base URL

Section titled “Base URL”
https://api.webdecoy.com/api

Authentication

Section titled “Authentication”
Authorization: Bearer sk_live_your_api_key

Or for user sessions:

Authorization: Bearer <auth0_jwt_token>

Authentication Endpoints

Section titled “Authentication Endpoints”

Callback (Complete Auth0 Login)

Section titled “Callback (Complete Auth0 Login)”
POST /auth/callback
Authorization: Bearer <auth0_jwt>

Response:

{
  "id": "user-uuid",
  "auth0_id": "auth0|123",
  "email": "[email protected]",
  "name": "User Name"
}

Get Current User

Section titled “Get Current User”
GET /auth/me
Authorization: Bearer <token>

Organizations

Section titled “Organizations”

Create Organization

Section titled “Create Organization”
POST /organizations
Authorization: Bearer <token>


{
  "name": "My Organization"
}

List Organizations

Section titled “List Organizations”
GET /organizations?page=1&page_size=50
Authorization: Bearer <token>

Get Organization

Section titled “Get Organization”
GET /organizations/{organization_id}
Authorization: Bearer <token>

Update Organization

Section titled “Update Organization”
PUT /organizations/{organization_id}
Authorization: Bearer <token>


{
  "name": "Updated Name"
}

Properties

Section titled “Properties”

Create Property

Section titled “Create Property”
POST /organizations/{organization_id}/properties
Authorization: Bearer <token>


{
  "name": "Production Website"
}

List Properties

Section titled “List Properties”
GET /organizations/{organization_id}/properties?page=1&page_size=50
Authorization: Bearer <token>

Get Property

Section titled “Get Property”
GET /properties/{property_id}
Authorization: Bearer <token>

Custom Domains

Section titled “Custom Domains”

Create Domain

Section titled “Create Domain”
POST /organizations/{organization_id}/domains
Authorization: Bearer <token>


{
  "domain": "decoy.example.com",
  "record_type": "A"
}

List Domains

Section titled “List Domains”
GET /organizations/{organization_id}/domains
Authorization: Bearer <token>

Verify Domain

Section titled “Verify Domain”
POST /domains/{domain_id}/verify
Authorization: Bearer <token>

SSL Certificates (ACME)

Section titled “SSL Certificates (ACME)”
POST /domains/{domain_id}/acme/challenge      # start a DNS-01 challenge
POST /domains/{domain_id}/acme/verify-dns     # check the TXT record
POST /domains/{domain_id}/acme/verify         # complete issuance
POST /domains/{domain_id}/acme/reset          # start over
POST /domains/{domain_id}/ssl/http01/initiate # HTTP-01 alternative (A-record domains)
POST /domains/{domain_id}/ssl/http01/complete
Authorization: Bearer <token>

Check SSL Status

Section titled “Check SSL Status”
POST /domains/{domain_id}/ssl-status
Authorization: Bearer <token>

Decoys

Section titled “Decoys”

Create Decoy

Section titled “Create Decoy”
POST /decoys
Authorization: Bearer <token>


{
  "custom_domain_id": "domain-uuid",
  "name": "Admin Backup Trap",
  "path": "/admin/backup.zip",
  "trigger_action": "log",
  "decoy_type": "link"
}

List Decoys

Section titled “List Decoys”
GET /decoys?page=1&page_size=50
Authorization: Bearer <token>

Get Decoy

Section titled “Get Decoy”
GET /decoys/{decoy_id}
Authorization: Bearer <token>

Update Decoy

Section titled “Update Decoy”
PATCH /decoys/{decoy_id}
Authorization: Bearer <token>


{
  "name": "Updated Name",
  "trigger_action": "block"
}

Delete Decoy

Section titled “Delete Decoy”
DELETE /decoys/{decoy_id}
Authorization: Bearer <token>

Detection Scripts

Section titled “Detection Scripts”

Create Detection Script

Section titled “Create Detection Script”
POST /organizations/{organization_id}/bot-scanners
Authorization: Bearer <token>


{
  "name": "Main Scanner",
  "enabled": true,
  "sensitivity": "medium"
}

List Detection Scripts

Section titled “List Detection Scripts”
GET /organizations/{organization_id}/bot-scanners
Authorization: Bearer <token>

Get Scanner Snippet

Section titled “Get Scanner Snippet”
GET /organizations/{organization_id}/bot-scanners/{scanner_id}/snippet
Authorization: Bearer <token>

Toggle Scanner

Section titled “Toggle Scanner”
PATCH /organizations/{organization_id}/bot-scanners/{scanner_id}/toggle
Authorization: Bearer <token>

Detections

Section titled “Detections”

List Detections

Section titled “List Detections”
GET /organizations/{organization_id}/detections?page=1&page_size=50
Authorization: Bearer <token>

Query Parameters:

Parameter Description
property_id Filter by property
source Detection source (decoy_link, endpoint, bot_scanner, sdk, honeypot_agent)
min_bot_score Minimum bot score
max_bot_score Maximum bot score
country Country code(s)
is_proxy true/false
is_vpn true/false
is_tor true/false
start_date ISO 8601 date
end_date ISO 8601 date
sort_by timestamp, bot_score
sort_order asc, desc

Get Detection

Section titled “Get Detection”
GET /organizations/{organization_id}/detections/{detection_id}
Authorization: Bearer <token>

Get Detection Stats

Section titled “Get Detection Stats”
GET /organizations/{organization_id}/detections/stats
Authorization: Bearer <token>

Get Hourly Stats

Section titled “Get Hourly Stats”
GET /organizations/{organization_id}/detections/stats/hourly
Authorization: Bearer <token>

Get Filter Options

Section titled “Get Filter Options”
GET /organizations/{organization_id}/detections/filter-options
Authorization: Bearer <token>

Export Detections

Section titled “Export Detections”
GET /organizations/{organization_id}/detections/export?format=csv
Authorization: Bearer <token>

Formats: csv, json. Respects the same filters as List Detections.

More Stats Endpoints

Section titled “More Stats Endpoints”
GET /organizations/{organization_id}/detections/geo
GET /organizations/{organization_id}/detections/stats/rule-executions
GET /organizations/{organization_id}/detections/stats/signals
GET /organizations/{organization_id}/detections/stats/ai-scrapers
GET /organizations/{organization_id}/detections/stats/ai-scrapers/by-name
GET /organizations/{organization_id}/detections/stats/llm-referrals
GET /organizations/{organization_id}/detections/stats/llm-referrals/by-platform
GET /organizations/{organization_id}/detections/stats/llm-referrals/top-pages
GET /organizations/{organization_id}/detections/stats/page-crawlers
GET /organizations/{organization_id}/detections/stats/radar
GET /organizations/{organization_id}/detections/stats/categories
GET /organizations/{organization_id}/detections/stats/top-sources
Authorization: Bearer <token>

Actors

Section titled “Actors”

Persistent cross-IP adversary identities. See Actors.

GET /organizations/{organization_id}/actors            # list; supports sort=threat|ip|property|last_seen, filter=rotating|enforced|ready
GET /organizations/{organization_id}/actors/stats      # org summary for the dashboard hero row
GET /organizations/{organization_id}/actors/{actor_id} # actor + IP/UA footprint + recent detections
Authorization: Bearer <token>

Enforcement

Section titled “Enforcement”

The WAF-enforcement pipeline (see Session Clearance). All routes are org-scoped.

POST   /organizations/{organization_id}/enforcement/cloudflare/preflight  # harmless zone live-test
GET    /organizations/{organization_id}/enforcement/mode                  # monitor | enforce
PUT    /organizations/{organization_id}/enforcement/mode
GET    /organizations/{organization_id}/enforcement/signatures            # active composite signatures (+ pushed count)
GET    /organizations/{organization_id}/enforcement/denylist              # clearance deny-list
POST   /organizations/{organization_id}/enforcement/denylist
DELETE /organizations/{organization_id}/enforcement/denylist/{device_fp}
GET    /organizations/{organization_id}/enforcement/routes                # token-enforced route scope
POST   /organizations/{organization_id}/enforcement/routes
DELETE /organizations/{organization_id}/enforcement/routes/{route_id}
GET    /organizations/{organization_id}/enforcement/allowlist             # verified-crawler categories
PUT    /organizations/{organization_id}/enforcement/allowlist
GET    /organizations/{organization_id}/enforcement/credentials           # machine service tokens
POST   /organizations/{organization_id}/enforcement/credentials
DELETE /organizations/{organization_id}/enforcement/credentials/{credential_id}
GET    /organizations/{organization_id}/enforcement/audit                 # append-only change log
Authorization: Bearer <token>

Response Actions

Section titled “Response Actions”

WHEN→THEN automations (see Response Actions).

GET    /organizations/{organization_id}/response-actions
POST   /organizations/{organization_id}/response-actions
PUT    /organizations/{organization_id}/response-actions/{id}
DELETE /organizations/{organization_id}/response-actions/{id}
Authorization: Bearer <token>

MITRE ATT&CK

Section titled “MITRE ATT&CK”

List Tactics

Section titled “List Tactics”
GET /mitre/tactics

Get Tactic Stats

Section titled “Get Tactic Stats”
GET /organizations/{organization_id}/mitre/stats
Authorization: Bearer <token>

Integrations

Section titled “Integrations”

Cloudflare

Section titled “Cloudflare”

Create Integration

Section titled “Create Integration”
POST /organizations/{organization_id}/integrations/cloudflare
Authorization: Bearer <token>


{
  "api_token": "cloudflare_token",
  "account_id": "account_id",
  "zone_id": "zone_id",
  "zone_name": "example.com"
}

Slack, Vercel, Datadog, Splunk, AWS WAF, Fastly, and CrowdStrike each have equivalent org-scoped CRUD + test endpoints under /organizations/{organization_id}/integrations/{provider}.

Webhooks

Section titled “Webhooks”

Create Webhook

Section titled “Create Webhook”
POST /organizations/{organization_id}/integrations/webhooks
Authorization: Bearer <token>


{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "on_detection": true,
  "min_bot_score": 70
}

Test Webhook

Section titled “Test Webhook”
POST /organizations/{organization_id}/integrations/webhooks/{webhook_id}/test
Authorization: Bearer <token>

API Keys

Section titled “API Keys”

Create API Key

Section titled “Create API Key”
POST /organizations/{organization_id}/api-keys
Authorization: Bearer <token>


{
  "name": "Production SDK",
  "scopes": ["detections:read", "detections:write"],
  "expires_in": 365
}

Response:

{
  "id": "key-uuid",
  "name": "Production SDK",
  "api_key": "sk_live_xxxxxxx",
  "key_prefix": "sk_live_xxx",
  "scopes": ["detections:read", "detections:write"]
}

Important: The full api_key is only returned once. Store it securely.

List API Keys

Section titled “List API Keys”
GET /organizations/{organization_id}/api-keys
Authorization: Bearer <token>

Revoke API Key

Section titled “Revoke API Key”
DELETE /organizations/{organization_id}/api-keys/{key_id}
Authorization: Bearer <token>

Billing

Section titled “Billing”

Get Plans

Section titled “Get Plans”
GET /billing/plans
Authorization: Bearer <token>

Create Checkout Session

Section titled “Create Checkout Session”
POST /billing/checkout-session
Authorization: Bearer <token>


{
  "organization_id": "org-uuid",
  "price_id": "price_xxx",
  "success_url": "https://app.example.com/billing/success",
  "cancel_url": "https://app.example.com/billing"
}

Get Subscription

Section titled “Get Subscription”
GET /organizations/{organization_id}/subscription
Authorization: Bearer <token>

Get Usage

Section titled “Get Usage”
GET /organizations/{organization_id}/billing/usage
Authorization: Bearer <token>

Ingest & SDK API

Section titled “Ingest & SDK API”

These endpoints live on the ingest service (base URL https://ingest.webdecoy.com) and are what the SDKs, detection scripts, and edge validators talk to.

Building a sensor for a stack we do not ship one for? The full wire contract — fields, the client signals block, client-IP resolution, and the fail-open behaviour a sensor must implement — is documented in the Sensor Protocol.

POST /api/v1/detect                        # submit a detection (Authorization: Bearer sk_live_...)
POST /api/v1/detect/public                 # browser tag only (aid + sid, unauthenticated)
POST /api/v1/clearance                     # mint a wd_clearance token (publishable site key: aid)
GET  /api/v1/clearance/config              # edge-validator config
POST /api/v1/page-serve                    # page-serve telemetry
POST /api/v1/verify-js                     # JS-execution verification
GET  /api/v1/auth/validate-key             # validate an API key
POST /api/v1/sdk/detect                    # SDK detection submissions
POST /api/v1/sdk/violations/batch          # SDK rules-engine violation batches
GET  /api/v1/sdk/ip/{address}/enrichment   # IP enrichment for SDK filter rules

Response Formats

Section titled “Response Formats”

Success Response

Section titled “Success Response”
{
  "data": { ... },
  "total": 100,
  "page": 1,
  "page_size": 50
}

Error Response

Section titled “Error Response”
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "status": 400
}

Common Status Codes

Section titled “Common Status Codes”
Code Meaning
200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Rate Limited
500 Server Error

Rate Limits

Section titled “Rate Limits”
Endpoint Type Limit
Read operations 100/minute
Write operations 30/minute
Detection submission 1000/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642680000