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. Values are illustrative. 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": 99.0, // number 0-100, always. How strongly the evidence indicates automation; see Reading the object
    "detectionClass": {
      // tagged by type: Human | AiAgent | Bot | IncompleteData
      "type": "Bot",
      "botType": "Scraper", // Bot only: Scraper | SearchEngine | HeadlessBrowser | Tool | HighVelocity
      "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": 90.0, // number 0-100. Strength of this piece of evidence
        "weight": 0.5, // number 0-1. How much this evidence counts toward confidence; 0 for recorded context
        "source": "user_agent_pattern", // which detector produced it (see Signal sources)
        "explanation": "User-Agent matched known agent pattern: GPTBot",
      },
      {
        "signalType": "network",
        "confidence": 90.0,
        "weight": 0.5,
        "source": "vendor_ip_feed",
        "explanation": "Vendor IP + User-Agent cross-match: OpenAI GPTBot (training crawler)",
        "metadata": { "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 | high_velocity | ai_agent
    "agentType": "GPTBot", // optional. Matched agent name, vendor id, KYA-OS proof 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.2.0",
    "rulesetHash": "sha256:…", // identifies the bundled detection rules
    "rulesetVersion": "0.2.0",
    // "buildSha": "..."          string, optional
  },

  "trace": [
    // array, always. One entry per engine stage that ran
    {
      "name": "detection",
      "verdict": "pass",
      "latencyMicros": 4,
      "reason": "AiCrawler (99% 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 measures how strongly the evidence indicates automation. It runs from 0 to 100 and weighs many independent signals together: network and TLS characteristics, HTTP and header consistency, browser and runtime integrity, behavior, and known-agent intelligence. Verified cryptographic identity takes precedence over heuristic evidence and scores at the top of the range. confidence is a score of the evidence, not a measured probability, a measure of certainty in the class, or a fraud-risk score. confidenceLevel gives its band, and riskScore is a separate, uncalibrated score.
No evidence is not proof of a human. Human with an empty signals list means nothing indicated automation, not that a person was confirmed. Weigh 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": "PolicyDenied", "detail": "Automated traffic is not allowed on /checkout", "policyId": "block-automation-on-checkout" } }

// 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	How strongly the evidence indicates automation, 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`, `high_velocity` or `ai_agent`.
`agentType`	string	When an agent or bot is named	Matched agent name, vendor id, KYA-OS proof issuer, or `kya-os` for the kya-http/2 profile.
`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`, `HeadlessBrowser`, `Suspicious`	`headless_browser`	`true`	`false`	`medium`
HTTP client or other bot	`Bot`, `Tool`, `Legitimate`	`tool`	`true`	`false`	`low`
High request rate	`Bot`, `HighVelocity`, `Suspicious`	`high_velocity`	`true`	`false`	`medium`
Verified vendor signature	`AiAgent`, with `agentType` and `vendor`	`ai_agent`	`true`	`false`	`low`
Verified KYA-OS agent (HTTP)	`{ "type": "AiAgent", "agentType": "kya-os" }`	`ai_agent`	`true`	`false`	`low`
Verified KYA-OS proof	`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, HeadlessBrowser, Tool, HighVelocity) 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	How much this evidence counts toward `confidence`, 0 to 1. Recorded context has weight 0.
`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 or vendor headers, or a header set inconsistent with a browser.	none
`vendor_ip_feed`	`network`	The request IP belongs to the vendor the User-Agent names.	`vendor_id`
`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.	Diagnostic only
`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.	Diagnostic only
`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`	A KYA-OS proof verified.	none
`a2a_agent_card`	`signature` or `pattern`	An A2A Agent Card was checked; `signature` when its signature verified.	none

Signal metadata keys not listed here are diagnostic and may change.

/api/v1/detect returns this same list on result.signals, unconditionally, on every response. /api/v1/enforce returns it only when you set options.includeDetectionResult.

Metadata keys

Key	Present on	Meaning
`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 is classified by other evidence.
`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`	A 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`	KYA-OS handshake 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.

Risk score

riskScore is an uncalibrated score of the same evidence, from 0 to 1. It is never derived from confidence and never feeds into it, and the two are on different scales, so they can differ widely. Don't convert one into the other.

Field	Type	Description
`riskScore`	number or null	0 to 1, rounded to two decimals. `null` when no uncalibrated score was produced: the request was verified by signature, the score is turned off in your integration's engine configuration, or detection was skipped. After an engine failure it is `null` or absent.
`riskScoreSource`	string or null	Which score `riskScore` was taken from. Always `uncalibrated` today. `null` exactly when `riskScore` is `null`.

They appear in the /api/v1/detect result, in /api/v1/enforce detection when you set options.includeDetectionResult, and in the .NET (RiskScore, RiskScoreSource) and Java (riskScore(), riskScoreSource()) SDK detection results. The engine object on this page, the Next.js and Express SDKs, and response headers do not carry them.

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" },
      "browser.language": { "value": "en-US" },
      "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. Values are illustrative.

"confidence": 1.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. The .NET and Java results also carry `riskScore` and `riskScoreSource`.
DNS gateway	`KYA-*` response headers, including `KYA-Detection-Class`, `KYA-Confidence` and `KYA-Reason-Codes`.
`POST /api/v1/detect`	A `result` projection with the full `signals` list, `reasonCodes`, `confidenceLevel`, `isAiCrawler`, `riskScore` and `riskScoreSource`.
`POST /api/v1/enforce`	The decision; with `options.includeDetectionResult`, the full `signals` list, `reasonCodes`, `confidenceLevel`, `isAiCrawler`, `riskScore` and `riskScoreSource`.
Pixel	A detection projection in the response and in the `checkpoint:detection` browser event.
Beacon	A receipt with the consolidated session id and 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`, `HeadlessBrowser`, `Tool`, `HighVelocity`
`detectionClass.legitimacy`	`Suspicious`, `Legitimate`
`botType`	`ai_crawler`, `search_engine`, `headless_browser`, `tool`, `high_velocity`, `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`

Values that contain mcp_i or mcp-i, such as mcp_i_handshake and detection/mcp-i-verified, keep the former name of KYA-OS, MCP-I.

Response Object