API

Scoring API reference

HTTP routes, request fields, decision schemas, response envelopes, and body limits.

On this page

Data plane routes

All paths below are relative to https://api.bastionsecurity.io/api/antibot. Requests use JSON. Server endpoints require both X-Site-Key and X-Secret-Key; browser endpoints use X-Site-Key and an allowlisted Origin.

Method / path	Authentication	Body / result
POST /fingerprint	Public	{fingerprint, behavior?} → token and device_id.
POST /collect	Public	VerificationRequest → decision. Observes request IP and user agent.
POST /events/batch	Public	{events: VerificationRequest[]} → per-item results.
POST /challenge	Public	{difficulty?} → challenge.
POST /challenge/verify	Public	{challenge_id, nonce} → proof validity.
POST /verify	Private	VerificationRequest → decision.
POST /verify/fingerprint	Private	{fingerprint, behavior?} → token and device_id.
POST /verify/batch	Private	{events: VerificationRequest[]} → per-item results.
POST /verify/challenge	Private	{difficulty?} → challenge.
POST /verify/challenge/verify	Private	{challenge_id, nonce} → proof validity.

bash

curl -X POST 'https://api.bastionsecurity.io/api/antibot/verify' \
  -H "X-Site-Key: $BASTION_SITE_KEY" \
  -H "X-Secret-Key: $BASTION_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "idempotency_key":"checkout-order_123-v1",
    "context":{
      "event_type":"checkout",
      "account_id":"customer_123",
      "order_amount":129.00,
      "payment_hash":"pm_provider_identifier"
    }
  }'

This server-only curl example omits browser telemetry for brevity. A production browser integration should forward the complete buildRequest result. A context-only verification has less evidence available.

VerificationRequest fields

Field	Type	Meaning
context	object · required	Authoritative event and account context.
token	string · optional	Registered fingerprint token, site-bound and valid for 10 minutes.
fingerprint	object · optional	Device evidence collected by the browser SDK.
behavior	object · optional	Interaction metrics and bounded samples.
environment	object · optional	Browser environment, timestamp, and freshness evidence.
headers	string map · optional	Supply only actual observed headers from your trusted server boundary.
username	string · optional	Display context for the account.
idempotency_key	string · optional	1–128 characters: letters, numbers, underscore, period, colon, hyphen. SDKs generate one when absent.

context field	Type	Contract
event_type	string · required	signup, login, promo_claim, checkout, or page_view.
account_id	string · required	Nonempty external account identifier; keep stable across events.
email	string · optional	Customer email from your trusted account record.
order_amount	number · optional	Finite nonnegative server-validated amount. Use a consistent currency convention for your site.
payment_hash	string · optional	Stable provider payment identifier or hash; never a raw card number.
promo_code	string · optional	Promo identifier, validated by your application.
ip_address / user_agent	string · optional	Actual client values observed at a trusted proxy/application boundary.
request_url	string · optional	Associated application URL.
login_succeeded	boolean · optional	Only after your server validates credentials. Browser claims are stripped.

Response envelope & decision

Successful JSON responses use {success: true, data, timestamp}. SDKs unwrap data. Treat any 2xx response as an HTTP success; Nest POST routes generally return 201. This example is illustrative evidence, not a guaranteed result for the sample request.

decision.json

{
  "success": true,
  "data": {
    "classification": "suspicious",
    "risk_score": 48,
    "risk_level": "medium",
    "action": "review",
    "request_id": "req_example",
    "device_id": "fp_example",
    "signals": [
      {
        "rule": "device_reuse",
        "score": 20,
        "description": "Device fingerprint is shared by multiple accounts."
      }
    ],
    "identity": {
      "cluster_id": "cluster_example",
      "linked_accounts": 3,
      "shared_devices": 1,
      "shared_ips": 1,
      "shared_payments": 0
    },
    "decision_ms": 14.2,
    "timestamp": "2026-10-14T12:00:00.000Z"
  },
  "timestamp": "2026-10-14T12:00:00.000Z"
}

Decision field	Meaning
classification	human, suspicious, or bot.
risk_score / risk_level	0–100 score; low <30, medium 30–59, high 60–84, critical 85–100.
action	allow, review, challenge, or block. Enforce this server policy result.
request_id / device_id	Recorded decision identifier and device fingerprint identifier.
signals	Array of {rule, score, description}; preserve evidence in your audit trail.
identity	Optional linked-account/shared-device/IP/payment counts; plan-gated.
challenge	Optional proof-of-work challenge descriptor.
decision_ms / timestamp	Scoring duration and decision time.

Payload limits

Limit	Value
Single scoring HTTP body	256 KiB.
Batch HTTP body	5 MiB; 1–50 events.
Per-event engine input	256 KiB.
Behavior samples	At most 2,048 total; SDK collection is further bounded.
Other management HTTP bodies	100 KiB.
Fingerprint token	10 minutes; bound to the site.

Malformed JSON returns 400 and oversized bodies return 413. Batch HTTP success does not mean every item was accepted. See the batch and error guides for recovery behavior.