Verify a Workload with VB-OS

Single Verification

Submit a workload and receive a verdict:

from vbos import VBOSClient

client = VBOSClient(api_key="YOUR_API_KEY")

result = client.verify(
    workload={
        "transaction_amount": 15000,
        "account_balance": 42000,
        "risk_score": 35
    },
    project="my-project",
    boundary_ref="payment-authorization",
)

if result.decision == "ASSERT":
    proceed_with_action()
else:
    handle_deferral(result.failure_reasons)

Batch Verification

Submit multiple workloads in a single request:

result = client.verify_batch(
    workloads=[
        {"transaction_amount": 15000, "account_balance": 42000, "risk_score": 35},
        {"transaction_amount": 75000, "account_balance": 42000, "risk_score": 35},
        {"transaction_amount": 5000, "account_balance": 10000, "risk_score": 10},
    ],
    project="my-project",
    boundary_ref="payment-authorization",
)

Each workload produces its own evaluation record.

Validation Only

Validate a workload against a boundary without recording an evaluation:

validation = client.validate(
    workload={
        "transaction_amount": 15000,
        "account_balance": 42000,
        "risk_score": 35
    },
    project="my-project",
    boundary_ref="payment-authorization",
)

Validation runs the same pipeline but does not create an immutable evaluation record. Use it for testing during development.

CLI Verification

vbos verify \
  --project my-project \
  --boundary payment-authorization \
  --evidence '{"transaction_amount": 15000, "account_balance": 42000, "risk_score": 35}'

cURL

curl -X POST https://api.vb-os.org/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-project",
    "boundary_ref": "payment-authorization",
    "workload": {
      "transaction_amount": 15000,
      "account_balance": 42000,
      "risk_score": 35
    }
  }'

Idempotency

The verify endpoint supports idempotency via the X-Idempotency-Key header:

curl -X POST https://api.vb-os.org/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If the same idempotency key is used again, the original evaluation result is returned without creating a new record.

Next Steps

• Your First ASSERT: understand the ASSERT response
• Your First DEFER: understand failure reasons
• Replay an Evaluation: reproduce past evaluations