Policy Evaluation

POST https://kovca.io/api/v1/policy/evaluate

Authenticate with your API key in the Authorization: Bearer header. Kovca evaluates only the policy text you send. It doesn't bring in other rules, regulations, or general knowledge, and its results are advisory, not legal or compliance determinations.

Request body

{
  "policy": {
    "id": "refund-policy",
    "version": "1.0",
    "text": "Refund requests are permitted within 30 days of delivery. Requests after 30 days require manager approval."
  },
  "request": {
    "description": "Customer requests a refund",
    "facts": {
      "days_since_delivery": 45
    }
  }
}

Response

{
  "request_id": "req_9rTk4MvWq1BzLs6D",
  "decision": "requires_review",
  "suggested_action": "request_approval",
  "requirements": [
    {
      "rule": "Requests after 30 days require manager approval.",
      "status": "requires_review"
    }
  ],
  "missing_information": [],
  "policy": {
    "id": "refund-policy",
    "version": "1.0"
  }
}

How a policy is evaluated

1. The policy text is split into rules: one per line, bullet, or numbered item, and one per sentence. Fragments under three words, such as headings, are skipped. Every rule Kovca returns appears word for word in your policy.
2. Each rule is judged on whether it applies to the request and, if it does, how the request fares under it, using only request.description and request.facts.
3. The rule results are combined with the fixed rules below.

Requirement statuses

• satisfied: the facts show the request meets the rule.
• not_satisfied: the rule explicitly forbids requests like this one, and the facts show this request falls under it.
• requires_review: the rule requires approval, describes an exception the request may qualify for, is ambiguous, or grants a permission the request doesn't qualify for without forbidding it.
• insufficient_information: the rule depends on a fact the request didn't supply. Missing facts are never assumed to be false.

Decision rules (first match wins)

1. The policy doesn't address the request, or no rule applies → insufficient_information, manual_review.
2. Rules in the policy contradict each other for this request → requires_review, manual_review. Kovca never picks the more permissive reading.
3. An exception may apply → requires_review, manual_review. Exceptions are never approved automatically.
4. A rule is not_satisfied → non_compliant, reject.
5. A rule requires approval → requires_review, request_approval.
6. A rule is ambiguous, or only grants a permission the request exceeds → requires_review, manual_review.
7. A rule needs facts that weren't supplied → insufficient_information, request_information.
8. Every applicable rule is satisfied → compliant, proceed.

Examples

curl https://kovca.io/api/v1/policy/evaluate \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policy": {
    "id": "refund-policy",
    "version": "1.0",
    "text": "Refund requests are permitted within 30 days of delivery. Requests after 30 days require manager approval."
  },
  "request": {
    "description": "Customer requests a refund",
    "facts": {
      "days_since_delivery": 45
    }
  }
}'

Errors

• 400 INVALID_REQUEST: a field is missing or invalid, the policy has no rule written as a sentence, or it has more than 40 rules.
• 401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

• Results are advisory. They are not legal advice or a certification of compliance.
• Kovca only quotes your rules; it doesn't name missing facts. missing_information lists the rules that need more information.
• Numeric thresholds in free text (amounts, dates, durations) are interpreted against your facts. Put exact numbers in request.facts and keep thresholds explicit for the most reliable results.
• Policies longer than 40 rules must be split across requests.
• Policies and requests are processed to produce the result and are not stored by Kovca.