REST action reference
Update a benefit
Update a benefit. 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": {
"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)$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"config": {
"type": "object",
"properties": {
"allowed_agents": {
"default": [],
"maxItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"google-agent"
]
}
},
"automation": {
"default": "assess",
"type": "string",
"enum": [
"allow",
"assess",
"deny"
]
},
"bot_evidence": {
"default": "optional",
"type": "string",
"enum": [
"optional",
"required"
]
},
"outcome_tracking": {
"default": "assume_granted",
"type": "string",
"enum": [
"assume_granted",
"report_outcome"
]
},
"missing_outcome_behavior": {
"default": "hold_eligibility",
"type": "string",
"enum": [
"hold_eligibility",
"release_eligibility"
]
},
"eligibility": {
"default": {
"kind": "once"
},
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "once"
}
},
"required": [
"kind"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "calendar"
},
"period": {
"type": "string",
"enum": [
"day",
"week",
"month"
]
},
"timezone": {
"type": "string",
"maxLength": 80
}
},
"required": [
"kind",
"period",
"timezone"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "rolling"
},
"days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
},
"required": [
"kind",
"days"
],
"additionalProperties": false
}
]
},
"valuation": {
"default": {
"currency": "USD",
"face_value": 0,
"delivery_cost": 0
},
"type": "object",
"properties": {
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"face_value": {
"type": "number",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
},
"delivery_cost": {
"type": "number",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
}
},
"required": [
"currency",
"face_value",
"delivery_cost"
],
"additionalProperties": false
}
},
"required": [
"allowed_agents",
"automation",
"bot_evidence",
"outcome_tracking",
"missing_outcome_behavior",
"eligibility",
"valuation"
],
"additionalProperties": false
},
"policy_key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"enforcement_mode": {
"type": "string",
"enum": [
"enforce",
"monitor"
]
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"id",
"name",
"config",
"policy_key",
"enforcement_mode",
"revision"
],
"additionalProperties": false
}Example request
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "Signup credits",
"config": {
"allowed_agents": [],
"automation": "assess",
"bot_evidence": "optional",
"outcome_tracking": "assume_granted",
"missing_outcome_behavior": "hold_eligibility",
"eligibility": {
"kind": "once"
},
"valuation": {
"currency": "USD",
"face_value": 100,
"delivery_cost": 20
}
},
"policy_key": "balanced",
"enforcement_mode": "enforce",
"revision": 1
}Response schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}Example success response
REST returns JSON. MCP returns the same object in structuredContent plus a transport request ID.
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "available"
}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: 5s. Retry only when error.retryable is true.
cURL
curl -X PATCH https://abusezero.com/v1/benefits/RESOURCE_ID \
-H "Authorization: Bearer $ABUSEZERO_SECRET_KEY" \
-H "AbuseZero-Organization: $ABUSEZERO_ORGANIZATION" \
-H "Idempotency-Key: operation_123" \
-H "Content-Type: application/json" \
--data '{"name":"Signup credits","config":{"allowed_agents":[],"automation":"assess","bot_evidence":"optional","outcome_tracking":"assume_granted","missing_outcome_behavior":"hold_eligibility","eligibility":{"kind":"once"},"valuation":{"currency":"USD","face_value":100,"delivery_cost":20}},"policy_key":"balanced","enforcement_mode":"enforce","revision":1}'Node SDK
const result = await abusezero.call("/v1/benefits/RESOURCE_ID", {
method: "PATCH",
input: {"id":"00000000-0000-4000-8000-000000000001","name":"Signup credits","config":{"allowed_agents":[],"automation":"assess","bot_evidence":"optional","outcome_tracking":"assume_granted","missing_outcome_behavior":"hold_eligibility","eligibility":{"kind":"once"},"valuation":{"currency":"USD","face_value":100,"delivery_cost":20}},"policy_key":"balanced","enforcement_mode":"enforce","revision":1},
idempotencyKey: "operation_123",
});MCP
abusezero_update_benefit({
"id": "00000000-0000-4000-8000-000000000001",
"name": "Signup credits",
"config": {
"allowed_agents": [],
"automation": "assess",
"bot_evidence": "optional",
"outcome_tracking": "assume_granted",
"missing_outcome_behavior": "hold_eligibility",
"eligibility": {
"kind": "once"
},
"valuation": {
"currency": "USD",
"face_value": 100,
"delivery_cost": 20
}
},
"policy_key": "balanced",
"enforcement_mode": "enforce",
"revision": 1,
"idempotency_key": "operation_123"
})