GUIDE

Custom policies

A policy is the set of thresholds an action's evidence must clear before its receipt is admissible. This guide shows you how to override the default policy per request, dry-run a change before you enforce it, and save a custom policy you can reuse.

Override the policy on a single request

Every call to POST /v1/evaluate runs against a policy. If you send no policy, the default applies. To tune the evaluation for one request, include a policyConfig object in the body. It overrides the default for that call only — nothing is saved.

The seven fields control how much evidence is required, how it must be qualified, and when a human has to be involved:

Match the policy to the stakes of the action. A production deployment deserves a strict policy: several typed sources, a confidence floor, mandatory provenance, and a human in the loop. A low-risk change — a docs edit, a dependency bump behind a green test suite — can clear a lighter bar without ceremony.

STRICT POLICY — PRODUCTION DEPLOY

{
  "minSources": 4,
  "minSourceTypes": 3,
  "minConfidence": 0.85,
  "requireProvenance": true,
  "requireReplay": true,
  "requireHumanApproval": true,
  "maxRiskScope": 3
}

LIGHTER POLICY — LOW-RISK CHANGE

{
  "minSources": 1,
  "minSourceTypes": 1,
  "minConfidence": 0.6,
  "requireProvenance": false,
  "requireReplay": true,
  "requireHumanApproval": false,
  "maxRiskScope": 10
}

Send the strict policy inline with a claim like this:

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/evaluate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "claim_id": "deploy-prod-2026-001",
    "entity": "acme-corp/widget-api",
    "claim": "Deploy v6.1.0 to production",
    "action": { "action_type": "deployment", "target_system": "github", "environment": "production" },
    "sources": [
      { "id": "evd_ci", "type": "ci", "uri": "https://example.com/ci/1", "confidence": 0.95, "content": "All tests green" },
      { "id": "evd_review", "type": "code_review", "uri": "https://example.com/pr/42", "confidence": 0.9, "content": "Approved by two reviewers" },
      { "id": "evd_human", "type": "human_approval", "uri": "https://example.com/approval/1", "confidence": 0.95, "content": "Release owner sign-off" }
    ],
    "policyConfig": {
      "minSources": 4,
      "minSourceTypes": 3,
      "minConfidence": 0.85,
      "requireProvenance": true,
      "requireReplay": true,
      "requireHumanApproval": true,
      "maxRiskScope": 3
    }
  }' | jq '.policy'

The response's policy object carries the verdict and a per-rule breakdown showing which thresholds passed and which failed — so a failing evaluation tells you exactly what evidence was missing.

Dry-run a policy before you enforce it

Tightening a policy on live traffic is how you discover, the hard way, that half your legitimate actions now get blocked. Avoid that. POST /v1/simulate evaluates a claim against a policy without persisting a receipt — same inputs, same scoring, no entry written to the ledger. Use it to see how a candidate policy would have ruled on real claims.

List and create managed policies

When a policy is worth reusing, you do not have to paste the same policyConfig into every request. Two endpoints manage saved policies:

GET /v1/policies returns the built-in policies the service ships with alongside any custom ones you have defined — a good starting point for seeing sensible defaults before you tune your own. POST /v1/policies stores a custom policy configuration you can then reuse across evaluations rather than redefining it inline each time.

Choosing thresholds

Pick thresholds from the evidence your pipeline actually produces, not from an ideal. If a typical merge carries a CI run and one review, setting minSources to 5 will block nearly everything and teach your team to route around the system. Start near the real median, then tighten deliberately.

• minSources and minSourceTypes: distinct types matter more than raw count. Three CI runs are still one kind of evidence; a CI run plus a review plus a human approval is genuinely independent corroboration. Prefer raising minSourceTypes over minSources.
• minConfidence: set it below your observed average so honest evidence clears it, but high enough to catch weak or guessed sources. A floor around 0.6 for routine changes and 0.85 for high-stakes ones is a defensible starting band — calibrate against your own data rather than overfitting to a few examples.
• maxRiskScope: tie it to blast radius. A change touching one isolated component can tolerate a wider scope than one touching shared infrastructure or security controls. Lower the cap as the stakes rise.

Tie escalation to risk rather than treating every gap as a hard stop. Setting requireHumanApproval to true routes an action lacking that approval to an ESCALATED verdict instead of BLOCKED — a human is asked to decide, and the receipt records that the decision was escalated. Reserve outright blocks for cases where no human review should be able to rescue the action, and use escalation for the larger set where a person, not a threshold, should make the call. For how each verdict is produced and what it means downstream, see policy verdicts.