REST action reference
Evaluate a benefit claim
Evaluate a benefit claim. REST and MCP call the same domain service, so a successful invocation returns the same canonical result.
Request schema
Unknown fields are rejected. Path parameters merge with the JSON body or query input before validation.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"agent_evidence": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"unsigned",
"verified",
"invalid",
"unrecognized",
"unavailable"
]
},
"claim_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"assessed_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"directory_version": {
"type": "string",
"const": "agents-v1"
},
"agent_id": {
"type": "string",
"enum": [
"google-agent"
]
},
"key_id": {
"type": "string",
"maxLength": 256
},
"signed_components": {
"maxItems": 32,
"type": "array",
"items": {
"type": "string",
"maxLength": 128
}
},
"source": {
"type": "string",
"const": "customer_backend"
}
},
"required": [
"status",
"claim_id",
"assessed_at",
"directory_version",
"signed_components",
"source"
],
"additionalProperties": false
},
"benefit": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"claim_id": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[\\x21-\\x7e]+$"
},
"subject": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"email": {
"type": "string",
"maxLength": 254,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"email_verified": {
"type": "boolean"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"context": {
"anyOf": [
{
"type": "object",
"properties": {
"ip": {
"anyOf": [
{
"type": "string",
"maxLength": 45
},
{
"type": "null"
}
]
},
"user_agent": {
"type": "string",
"maxLength": 512
},
"session_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"identifiers": {
"type": "object",
"properties": {
"device_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"device_token": {
"type": "string",
"maxLength": 4096
},
"browser_cookie_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"payment": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[\\x21-\\x7e]+$"
},
"scope": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[\\x21-\\x7e]+$"
},
"fingerprint": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"provider",
"scope",
"fingerprint"
],
"additionalProperties": false
},
"phone_hash": {
"type": "object",
"properties": {
"algorithm": {
"type": "string",
"const": "hmac-sha256"
},
"key_version": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[\\x21-\\x7e]+$"
},
"value": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"algorithm",
"key_version",
"value"
],
"additionalProperties": false
},
"phone_verified": {
"type": "boolean"
},
"custom": {
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"value_hash": {
"type": "object",
"properties": {
"algorithm": {
"type": "string",
"const": "hmac-sha256"
},
"key_version": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[\\x21-\\x7e]+$"
},
"value": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"algorithm",
"key_version",
"value"
],
"additionalProperties": false
}
},
"required": [
"key",
"value_hash"
],
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"required": [
"benefit",
"claim_id",
"subject"
],
"additionalProperties": false
}Example request
{
"benefit": "signup_credits",
"claim_id": "claim_customer_123",
"subject": {
"external_id": "customer_123",
"email": "alex@example.com",
"email_verified": true
},
"context": {
"ip": "192.0.2.10"
}
}Response schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"result": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"ai_abuse_risk_score": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 100
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"result"
],
"additionalProperties": {}
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "skipped"
},
"reason": {
"type": "string",
"enum": [
"billing_overdue",
"service_inactive",
"trial_allowance_exhausted",
"insufficient_credits",
"custom_allowance_exhausted"
]
}
},
"required": [
"status",
"reason"
],
"additionalProperties": false
}
]
}Example success response
REST returns JSON. MCP returns the same object in structuredContent plus a transport request ID.
{
"id": "00000000-0000-4000-8000-000000000001",
"result": "allow",
"ai_abuse_risk_score": 0
}Errors and recovery
Common statuses: 422 invalid input, 403 missing scope or organization access, 404 not found, 409 revision or idempotency conflict, 429 rate limit, 504 deadline exceeded.Include the request ID from the error envelope when you contact support.
Idempotency and deadlines
Send a stable Idempotency-Key and reuse it only for an exact retry of this mutation.Server deadline: 1.5s. Retry only when error.retryable is true.
cURL
curl -X POST https://abusezero.com/v1/evaluations \
-H "Authorization: Bearer $ABUSEZERO_SECRET_KEY" \
-H "AbuseZero-Organization: $ABUSEZERO_ORGANIZATION" \
-H "Idempotency-Key: operation_123" \
-H "Content-Type: application/json" \
--data '{"benefit":"signup_credits","claim_id":"claim_customer_123","subject":{"external_id":"customer_123","email":"alex@example.com","email_verified":true},"context":{"ip":"192.0.2.10"}}'Node SDK
const result = await abusezero.call("/v1/evaluations", {
method: "POST",
input: {"benefit":"signup_credits","claim_id":"claim_customer_123","subject":{"external_id":"customer_123","email":"alex@example.com","email_verified":true},"context":{"ip":"192.0.2.10"}},
idempotencyKey: "operation_123",
});MCP
abusezero_create_evaluation({
"benefit": "signup_credits",
"claim_id": "claim_customer_123",
"subject": {
"external_id": "customer_123",
"email": "alex@example.com",
"email_verified": true
},
"context": {
"ip": "192.0.2.10"
},
"idempotency_key": "operation_123"
})