Every field Checkpoint returns for a request: the verdict, the evidence behind it, and the engine that produced it

Every Checkpoint integration runs the same detection engine, and every verdict it produces is a single object, the VerifyResult. This page documents that object in full: every field, when it is present, and what its values mean.

What your integration receives from the object depends on the surface you installed and on whether full response delivery is enabled for your project.

Full response delivery

By default, each integration returns a projection of this object: headers from the SDKs and the DNS gateway, the result of /api/v1/detect, and the stored record through the read-back API. With full response delivery enabled, Checkpoint sends the complete object documented here, including every signal, reason code and captured attribute. Vouched enables full response delivery per project or per organization. Contact your account team to turn it on.

The response object, fully expanded

The example below is a GPTBot crawler request from an OpenAI IP address, evaluated in observe mode against a policy that allows it. Comments give each field's type and when it appears.

{
  "decision": { "kind": "Permit", "policyId": "allow-search-and-ai-crawlers" }, // Permit | Block | Challenge | Redirect | Instruct (tag = kind)

  "detectionDetail": {
    "isAgent": false, // boolean, always. true only for the AiAgent class; route on detectionClass instead
    "isBot": true, // boolean, optional. Omitted when the class is IncompleteData
    "isAiCrawler": true, // boolean, optional. Omitted when the class is IncompleteData
    "confidence": 93.0, // number 0-100, always. Detection score, not a calibrated probability
    "detectionClass": {
      // tagged by type: Human | AiAgent | Bot | IncompleteData
      "type": "Bot",
      "botType": "Scraper", // Bot only: Scraper | SearchEngine | Tool
      "legitimacy": "Suspicious", // Bot only: Suspicious | Legitimate
    },
    "confidenceLevel": "very_high", // low | medium | high | very_high; bands at /docs/detect#confidence-scores
    "reasons": [
      // string[], always. Human-readable, one per piece of classifying evidence
      "User-Agent matched known agent pattern: GPTBot",
      "Vendor IP + User-Agent cross-match: OpenAI GPTBot (training crawler)",
    ],
    "signals": [
      // array, always (may be empty). The evidence behind the verdict
      {
        "signalType": "pattern", // signature | pattern | behavioral | network | fingerprint
        "confidence": 95.0, // number 0-100. Strength of this piece of evidence
        "weight": 1.0, // number 0-1. 1.0 identity evidence, 0.4 heuristics, 0 recorded context
        "source": "user_agent_pattern", // which detector produced it (see Signal sources)
        "explanation": "User-Agent matched known agent pattern: GPTBot",
      },
      {
        "signalType": "network",
        "confidence": 93.0,
        "weight": 1.0,
        "source": "vendor_ip_feed",
        "explanation": "Vendor IP + User-Agent cross-match: OpenAI GPTBot (training crawler)",
        "metadata": { "tier": 2, "vendor_id": "openai_gptbot" }, // object, optional. Omitted when empty
      },
    ],
    "detectedAgent": { "type": "bot", "name": "GPTBot" }, // optional. type: ai_agent | bot; vendor set on verified vendor signatures
    "botType": "ai_crawler", // optional. ai_crawler | search_engine | headless_browser | tool | ai_agent
    "agentType": "GPTBot", // optional. Matched agent name, vendor id, MCP-I issuer, or "kya-os"
    "verificationMethod": "pattern", // optional. none | pattern | signature | kya-http | kya-http-delegated | a2a | mcp_i_handshake | tier1_rfc9421 | error
    "assurance": "anonymous", // always. anonymous | attested-bearer | key-bound | delegated
    "riskLevel": "high", // low | medium | high
    "forgeabilityRisk": "medium", // low (cryptographically verified) | medium (pattern) | high (engine error)
    "timestamp": 1789500000, // integer, always. Unix seconds
    // "metadata": { ... }        object, optional. Path-specific keys (see Metadata keys)
    // "requestId": "..."         string, optional. Added by some integrations; never set by the engine
    // "engine": { ... }          object, optional. Copy of engineInfo on signature-verified paths
    // "grantedScopes": [ ... ]   string[], optional. Present when a delegation was verified
  },

  "enforcementMode": "observe", // enforce | observe. In observe mode your integration records the decision without acting on it

  "engineInfo": {
    "name": "checkpoint-engine-wasm", // checkpoint-engine-wasm | checkpoint-engine-wasi | checkpoint-engine-native
    "version": "0.1.1",
    "rulesetHash": "sha256:t1:f23d9a07…:t2:2e6a63de…:t3:fba4ef9a…:t4:unset", // hash of the bundled rules, per tier
    "rulesetVersion": "0.1.1",
    // "buildSha": "..."          string, optional
  },

  "trace": [
    // array, always. One entry per engine stage that ran
    {
      "name": "detection",
      "verdict": "pass",
      "latencyMicros": 4,
      "reason": "AiCrawler (93% confidence)",
    },
    { "name": "reputation", "verdict": "pass", "latencyMicros": 0 },
    { "name": "policy", "verdict": "pass", "latencyMicros": 0 },
  ],

  // "network": { "trueIp", "asn", "isp", "routingType", "proxy" }   object, optional. Present when network context was available
}

Route on detectionClass, not isAgent

isAgent is true only for the AiAgent class. Crawlers such as GPTBot are Bot, so isAgent is false for them. Other surfaces use a broader meaning: the /api/v1/detect result and stored detection records treat any non-human class as an agent. Use detectionClass and botType to decide what to do with a request.

Reading the object

confidence is a detection score. It comes from fixed values per rule: 10 when nothing matched, 40 for suspicious headers or weak automation evidence, 55 to 60 for HTTP client libraries, 65 for a browser User-Agent on a non-browser TLS stack, 80 for headless or self-disclosed automation, 93 to 95 for a named or vendor-attributed agent, and 99 to 100 for a cryptographically verified agent. It is not a calibrated probability and not a fraud-risk score.
No evidence is not proof of a human. Human at confidence 10 means no agent indicator matched. A script that copies a browser's User-Agent and sends nothing else also lands there, so treat low-evidence Human verdicts accordingly in your own risk logic.
Identity and heuristics are separate axes. verificationMethod and assurance say what was cryptographically proven. signals say what heuristics observed. A GPTBot User-Agent from an OpenAI IP address is strong heuristic evidence, but its assurance is still anonymous.
Scales differ by surface. confidence is 0 to 100 in this object, in /api/v1/enforce and in the extended read-back. The legacy detections list and webhook payloads use 0 to 1.
Expect additions. New signal sources, metadata keys and reason codes are added over time. Ignore values you don't recognize rather than rejecting the response.

Top-level fields

Field	Type	Present	Description
`decision`	object	Always	The policy outcome, tagged by `kind`. See Decision.
`detectionDetail`	object	Always	Classification, score and evidence. See Detection detail.
`enforcementMode`	string	Always	`enforce` or `observe`.
`engineInfo`	object	Always	The engine build that produced the verdict.
`trace`	array	Always	Per-stage audit entries: `name`, `verdict`, `latencyMicros`, optional `reason`.
`network`	object	When network context was available	IP intelligence for the request. See Captured context.

Decision

decision is tagged by kind. Each kind carries its own payload.

// Permit: the request may proceed. policyId names the deciding policy when there is one
{ "kind": "Permit", "policyId": "allow-search-and-ai-crawlers" }

// Block: the request is refused. reason is tagged by kind (see the table below)
{ "kind": "Block", "reason": { "kind": "Tier3UAMatch", "pattern_id": "Automation Tools", "pattern_kind": "HeadlessBrowser", "confidence": 80 } }

// Challenge: the client must step up before retrying
{
  "kind": "Challenge",
  "params": {
    "nonce": "c2f1…",
    "audience": "https://app.example.com",
    "expiresAt": 1789500300,
    "algorithmsAccepted": ["EdDSA", "ES256"],
    "minAssurance": "delegated", // optional
    "policyId": "require-delegation", // optional
    "challengeType": "human_step_up", // optional. Omitted for delegation; browser_integrity | human_step_up
  },
}

// Redirect: send the client elsewhere
{ "kind": "Redirect", "target": { "url": "https://app.example.com/verify", "reason": "…", "state": "…", "policyId": "…" } }

// Instruct: tell an agent how to make an acceptable request
{
  "kind": "Instruct",
  "payload": {
    "problem": "…",
    "title": "…",
    "suggestedActions": [{ "kind": "UseDifferentScope", "scope": "read:documents" }],
    "policyId": "…", // optional
  },
}

suggestedActions[].kind is one of UseDifferentScope (scope), UpdateRequestField (field, acceptedValues), UpgradeProtocolVersion (version) or Other (code, detail).

Block reasons

Block reason fields are written in snake_case, unlike the rest of the object.

`reason.kind`	Fields	Meaning
`Revoked`	none	A presented credential is revoked, or its status could not be confirmed.
`InvalidSignature`	none	A signature did not verify.
`Unauthenticated`	none	A proof was missing, unresolvable, replayed, or bound to the wrong holder, audience or session.
`Expired`	none	A credential or proof is outside its validity window.
`OutOfScope`	`requested`, `granted[]`	The delegation does not grant the scope the request needs.
`LowReputation`	`score`, `threshold`	Reputation is below the configured threshold.
`PolicyDenied`	`detail`, `policyId` (optional)	A policy rule denied the request, including a delegation that needs a stronger proof.
`AgentAttribution`	`vendor`, `tier`, `confidence`	Blocked on vendor attribution.
`ParseError`	`detail`	The request could not be parsed for verification.
`Tier3UAMatch`	`pattern_id`, `pattern_kind`, `confidence`	Blocked on a User-Agent pattern match. `pattern_kind` is `KnownAiAgent`, `AiCrawler` or `HeadlessBrowser`.

The table is in order of severity. When more than one outcome applies, Redirect wins, then Challenge, then Instruct, then the most severe Block reason.

Detection detail

Field	Type	Present	Description
`isAgent`	boolean	Always	`true` only for the `AiAgent` class.
`isBot`	boolean	Omitted for `IncompleteData`	Whether the client is automated.
`isAiCrawler`	boolean	Omitted for `IncompleteData`	Whether the client is an AI training or retrieval crawler.
`confidence`	number	Always	Detection score, 0 to 100.
`detectionClass`	object	Always	Classification, tagged by `type`. See Classes.
`confidenceLevel`	string	Always	`low`, `medium`, `high` or `very_high`; see Confidence scores.
`reasons`	string[]	Always	Human-readable explanations of the classifying evidence.
`signals`	array	Always, may be empty	The evidence behind the verdict. See Signals.
`detectedAgent`	object	When an agent or bot is named	`type` (`ai_agent` or `bot`), `name`, and `vendor` on verified vendor signatures.
`botType`	string	For bots and verified agents	`ai_crawler`, `search_engine`, `headless_browser`, `tool` or `ai_agent`.
`agentType`	string	When an agent or bot is named	Matched agent name, vendor id, MCP-I issuer, or `kya-os` for KYA-OS agents.
`verificationMethod`	string	Omitted when a presented credential was rejected	How the identity was established. See Enumerations.
`assurance`	string	Always	The strongest identity binding proven: `anonymous`, `attested-bearer`, `key-bound` or `delegated`.
`riskLevel`	string	Always	`low`, `medium` or `high`.
`forgeabilityRisk`	string	Always	How easily the evidence could be forged: `low`, `medium` or `high`.
`metadata`	object	When the evidence path adds keys	See Metadata keys.
`timestamp`	integer	Always	Unix seconds.
`requestId`	string	When your integration sets one	Not set by the engine.
`engine`	object	Signature-verified paths	Same shape as `engineInfo`.
`grantedScopes`	string[]	When a delegation was verified	The scopes the delegation grants.

Classes

Classification	`detectionClass`	`botType`	`isBot`	`isAiCrawler`	`riskLevel`
Human	`{ "type": "Human" }`	none	`false`	`false`	`low`
Known AI agent (User-Agent)	`{ "type": "AiAgent", "agentType": "ChatGPT" }`	none	`false`	`false`	`high`
AI crawler	`Bot`, `Scraper`, `Suspicious`	`ai_crawler`	`true`	`true`	`high`
Search engine crawler	`Bot`, `SearchEngine`, `Legitimate`	`search_engine`	`true`	`false`	`low`
Headless or automated browser	`Bot`, `Scraper`, `Suspicious`	`headless_browser`	`true`	`false`	`medium`
HTTP client or other bot	`Bot`, `Tool`, `Legitimate`	`tool`	`true`	`false`	`low`
Verified vendor signature	`AiAgent`, with `agentType` and `vendor`	`ai_agent`	`true`	`false`	`low`
Verified KYA-OS agent	`{ "type": "AiAgent", "agentType": "kya-os" }`	`ai_agent`	`true`	`false`	`low`
Verified MCP-I agent	`AiAgent`, with `agentType` set to the issuer	none	`false`	`false`	`low`
Incomplete data	`{ "type": "IncompleteData" }`	none	omitted	omitted	`medium`

AiAgent may also carry vendor and model. Bot carries botType (Scraper, SearchEngine, Tool) and legitimacy (Suspicious, Legitimate).

Signals

Each entry in detectionDetail.signals is one piece of evidence.

Field	Type	Description
`signalType`	string	`signature`, `pattern`, `behavioral`, `network` or `fingerprint`.
`confidence`	number	Strength of this evidence, 0 to 100.
`weight`	number	Contribution to the combined score: 1.0 identity evidence, 0.4 heuristics, 0 for recorded context.
`source`	string	The detector that produced it.
`explanation`	string	Human-readable description.
`metadata`	object	Source-specific details. Omitted when empty.

Signal sources

`source`	`signalType`	What it records	`metadata` keys
`user_agent_pattern`	`pattern`	The User-Agent matched a known agent pattern.	none
`header_heuristic`	`pattern`	Agent-specific or vendor headers, or missing standard browser headers.	none
`vendor_ip_feed`	`network`	The request IP belongs to the vendor the User-Agent names.	`vendor_id`, `tier`
`ip_heuristic`	`network`	An IP-only heuristic matched.	none
`ip_intelligence`	`network`	IP intelligence flagged a proxy, VPN or hosting network.	`routing_type`, `proxy_type`
`ua_tls_mismatch`	`fingerprint`	A browser User-Agent arrived on a TLS stack used by non-browser tooling.	`ja4_b`
`transport.ja4`	`fingerprint`	The TLS client fingerprint observed at the edge. Recorded context.	`tls_ja4`, `tls_version`
`transport.cloudflare_bot_management`	`network`	Cloudflare's bot management score, on the DNS gateway.	`cf_bot_score`, `cf_verified_bot`
`scanner_misclassification_hint`	`network`	Cloudflare's score contradicted a human classification.	`cf_bot_score`
`client_headless_escalation`	`fingerprint`	Browser automation evidence from the Beacon changed the classification.	`disclosed`
`client.attributes`	`fingerprint`	Device and browser attributes from the Beacon or pixel. Recorded context.	`attributes`
`behavioural.interaction`	`behavioral`	Interaction counters. Recorded context.	`mouse_movements`, `click_count`, `scroll_depth_percent`, `time_on_page_ms`
`session_velocity`	`behavioral`	Request volume for the session. Recorded context.	`request_count_in_window`, `window_seconds`, `requests_per_minute`
`tier1_rfc9421`	`signature`	A vendor's HTTP message signature verified (Web Bot Auth).	none
`kya_http_binding`	`signature`	A KYA-OS HTTP signature verified.	none
`kya_delegation_bearer`	`signature`	A KYA-OS delegation credential verified.	none
`mcp_i`	`signature`	An MCP-I proof verified.	none
`a2a_agent_card`	`signature` or `pattern`	An A2A Agent Card was checked; `signature` when its signature verified.	none

/api/v1/detect returns a single summary signal with source kya_os_engine instead of this list. /api/v1/enforce returns the full list when you set options.includeDetectionResult.

Metadata keys

Key	Present on	Meaning
`verified_tier`	Verified signatures	`1` for cryptographic verification.
`verified_protocol`	Verified signatures	`rfc9421` or `kya-http`.
`verified_vendor`, `key_id`	Verified vendor signatures	The vendor and the key that signed.
`covered_components`	Verified vendor signatures	The HTTP message components the signature covers.
`tier1_failure_reason`, `tier1_skipped_reason`	Vendor signatures that failed or were not checked	Why verification did not succeed. The request falls back to pattern detection.
`agent_did`	KYA-OS agents	The agent's DID.
`kya_session_id`	KYA-OS delegation credentials	The delegation session.
`kya_error_code`	Rejected KYA-OS credentials	A `kyaos/…` error code.
`a2a_card_name`, `a2a_card_provider`	Verified A2A Agent Cards	The card's name and provider.
`a2a_unverified_reason`	A2A Agent Cards that did not verify	Why the card was not verified.

Keys not listed here are diagnostic and may change.

Reason codes

Reason codes are the machine-readable form of reasons: an ordered list of detection/* codes, most significant evidence first and never empty. They appear in /api/v1/enforce (detection.reasonCodes), in the extended read-back (reasonCodes), and in the DNS gateway's KYA-Reason-Codes header (up to five).

Code	Meaning
`detection/tier1-attribution-verified`	A vendor signature verified.
`detection/rfc9421-signature-verified`	An HTTP message signature verified.
`detection/signature-verified`	A KYA-OS HTTP signature verified.
`detection/delegation-verified`	A KYA-OS HTTP signature and delegation verified.
`detection/mcp-i-verified`	An MCP-I or KYA-OS handshake verified.
`detection/did-signature-verified`	A DID signature verified.
`detection/a2a-verified`	An A2A Agent Card verified.
`detection/verification-error`	Verification ended in an error.
`detection/ua-pattern-match`	The User-Agent matched a known agent pattern.
`detection/header-heuristic`	A header heuristic fired.
`detection/ip-heuristic`	An IP heuristic fired.
`detection/vendor-ip-corroborated`	The request IP matched the vendor the User-Agent names.
`detection/ip-intelligence-proxy-signal`	IP intelligence flagged a proxy, VPN or hosting network.
`detection/ja4-fingerprint-match`	A TLS (JA4) fingerprint was recorded for the request.
`detection/ua-tls-mismatch`	A browser User-Agent arrived on a non-browser TLS stack.
`detection/client-integrity-failure`	Browser integrity checks failed.
`detection/client-attribute-signal`	Browser or device attributes were recorded.
`detection/behavioral-signal`	Interaction counters were recorded.
`detection/mcp-i-signal`	MCP-I evidence was present.
`detection/kya-http-binding-signal`	KYA-OS HTTP signature evidence was present.
`detection/kya-delegation-bearer-signal`	KYA-OS delegation credential evidence was present.
`detection/tier1-attribution-signal`	Vendor signature evidence was present.
`detection/ai-crawler-flag`	The client is an AI crawler.
`detection/zero-evidence-human`	Classified as human with no evidence.
`detection/incomplete-data-override`	Not enough evidence to classify.
`detection/classified-without-signal-evidence`	Classified as automated without a mapped signal.

Captured context

Alongside the verdict, Checkpoint stores the context it observed for the request: TLS details from the DNS gateway, device and browser attributes from the Beacon or pixel, interaction counters, and IP intelligence. It is part of the stored detection record and of full response delivery.

{
  "transport": {
    // DNS gateway only
    "tlsJa4": "t13d1516h2_8daaf6152771_02713d6af862",
    "tlsVersion": "TLSv1.3",
    "cfBotScore": 2, // when Cloudflare Bot Management is available
    "cfVerifiedBot": false,
    "asn": 16509,
    "asOrganization": "Amazon.com, Inc.",
  },
  "client": {
    // Beacon, pixel and native collectors. Each attribute is { "value": "<string>" }
    "attributes": {
      "device.platform": { "value": "MacIntel" },
      "browser.timezone": { "value": "America/Chicago" },
      "screen.resolution": { "value": "1512x982" },
      "client.webdriver": { "value": "false" },
      "platform.hardwareConcurrency": { "value": "10" },
    },
  },
  "behavioural": {
    "mouseMovements": 42,
    "clickCount": 3,
    "scrollDepthPercent": 60,
    "timeOnPageMs": 18450,
  },
  "network": {
    "trueIp": "3.19.44.10",
    "asn": 16509,
    "isp": "Amazon.com, Inc.",
    "routingType": "hosting", // residential | mobile | datacenter | hosting | unknown
    "proxy": { "isProxy": true, "proxyType": "datacenter", "confidence": 95 }, // vpn | tor | datacenter | residential_proxy | unknown
  },
}

A missing network field means no data was available for that address, not that the address is clean.

Examples by evidence path

Each example shows only the fields that differ from the fully expanded object.

"confidence": 10.0,
"detectionClass": { "type": "Human" },
"confidenceLevel": "low",
"reasons": ["No known agent indicators matched"],
"signals": [],
"verificationMethod": "none",
"riskLevel": "low"

What each integration returns

Integration	What you receive today
SDK middleware (Java, .NET, Next.js, Express)	Response headers with class, confidence, agent and verification method, and the SDK's typed result in your application.
DNS gateway	`KYA-*` response headers, including `KYA-Detection-Class`, `KYA-Confidence` and `KYA-Reason-Codes`.
`POST /api/v1/detect`	A `result` projection with one summary signal.
`POST /api/v1/enforce`	The decision; with `options.includeDetectionResult`, the full `signals` list, `reasonCodes`, `confidenceLevel` and `isAiCrawler`.
Pixel	A detection projection in the response and in the `checkpoint:detection` browser event.
Beacon	A receipt with the consolidated session id and, when configured, a signed browser posture token.
Read-back API	The stored record, including `signals`, `network`, `geo`, `decision` and `reasonCodes`, with `?view=extended`.
Webhooks	`detection.created` and `enforcement.decided` summaries.
Full response delivery	The complete object on this page. Enabled by Vouched per project or organization.

Enumerations

Field	Values
`decision.kind`	`Permit`, `Block`, `Challenge`, `Redirect`, `Instruct`
`detectionClass.type`	`Human`, `AiAgent`, `Bot`, `IncompleteData`
`detectionClass.botType`	`Scraper`, `SearchEngine`, `Tool`
`detectionClass.legitimacy`	`Suspicious`, `Legitimate`
`botType`	`ai_crawler`, `search_engine`, `headless_browser`, `tool`, `ai_agent`
`verificationMethod`	`none`, `pattern`, `signature`, `kya-http`, `kya-http-delegated`, `a2a`, `mcp_i_handshake`, `tier1_rfc9421`, `error`
`assurance`	`anonymous`, `attested-bearer`, `key-bound`, `delegated`, from weakest to strongest
`confidenceLevel`	`low`, `medium`, `high`, `very_high`
`riskLevel`, `forgeabilityRisk`	`low`, `medium`, `high`
`signals[].signalType`	`signature`, `pattern`, `behavioral`, `network`, `fingerprint`
`enforcementMode`	`enforce`, `observe`
`trace[].name`	`detection`, `identity`, `signature`, `revocation`, `expiration`, `scope`, `reputation`, `policy`
`trace[].verdict`	`pass`, `fail`, `skip`
`params.challengeType`	`delegation` (default, omitted), `browser_integrity`, `human_step_up`
`network.routingType`	`residential`, `mobile`, `datacenter`, `hosting`, `unknown`
`network.proxy.proxyType`	`vpn`, `tor`, `datacenter`, `residential_proxy`, `unknown`
`engineInfo.name`	`checkpoint-engine-wasm`, `checkpoint-engine-wasi`, `checkpoint-engine-native`

Response Object