Manual

Gates

A gate answers one question at the moment you are about to let an identity do something: should you? Dregs reads the scores and badges it already has and recommends allow, review, or deny. You enforce the recommendation.

When to Use a Gate

Use a gate at a decision you make in your own application, such as granting trial credits or starting an expensive action. The slug is a label you choose. Dregs does not know what the action is, and the slug is not tied to any particular product.

A gate is not a score, and it does not change one. Scoring still runs as events arrive. The gate is a deterministic read of that stored result, so the same identity and the same gate produce the same verdict until the scores or badges change.

What a Gate Contains

  • Slug. Unique for your team. Lowercase letters, digits, and underscores, starting with a letter, up to 64 characters. For example grant_trial_credits or start_expensive_action.
  • Mode. enforce returns the verdict the rules produced. dry_run evaluates and logs that verdict, then returns allow and sets wouldBe to the real one, so you can watch a gate before you act on it.
  • Rules. An ordered list. Each rule has an optional description, match (all or any, and all when you omit it), one or more conditions, and a verdict of allow, review, or deny. The first matching rule wins. There are no nested groups.
  • Default. The verdict when no rule matches.

A team can have 100 gates. A gate can have 50 rules, and a rule 20 conditions. Create and edit gates with the API or from an AI agent. The dashboard does not edit them yet, and it does not show the check log yet.

Conditions

v1 has four condition types. They read stored data only. No model runs at check time.

Each condition is one predicate. badge_present and badge_absent each take a single badge slug, the badge's source id, the same string an escalation rule uses. A list under badges is rejected. score compares one stored score with <, <=, >=, or >. The score name is humanity, authenticity, uniqueness, or behavior. There is no equality operator. score_missing matches when that stored score is null. A score comparison does not match a missing score, so a missing authenticity score is not "authenticity under 40".

match says how the conditions in that one rule combine. all means every condition. any means one of them. To allow only when none of these badges are present, set match to all and add one badge_absent per slug:

{
  "description": "Allow only when none of these badges are present",
  "match": "all",
  "verdict": "allow",
  "conditions": [
    {"type": "badge_absent", "badge": "suspicious"},
    {"type": "badge_absent", "badge": "bot"}
  ]
}

To match when any of those badges is present, set match to any and add one badge_present per slug. Another rule is how you say something the first rule does not cover.

These are the full-analysis scores Dregs stores on the identity, on a 0 to 100 scale. They are not the number from Authenticity Check (POST /api/tools/authenticity-check). That call runs a fresh scoring pass on the fields you send, including an email you have not tracked. A gate reads scores that are already stored. Both calls count as an operation against the monthly operations quota. A gate check does not count as a check.

Checking

POST /api/identities/{id}/actions/check with your secret key:

{
  "gate": "grant_trial_credits",
  "context": {"action": "grant_trial_credits"}
}

context is optional. It is stored on the check log and is not used to decide the verdict. Do not put personal data in it. The response looks like this:

{
  "verdict": "deny",
  "gate": "grant_trial_credits",
  "matchedRule": {"index": 0, "description": "Low authenticity"},
  "mode": "enforce",
  "scores": {"humanity": 80, "authenticity": 22, "uniqueness": 91, "behavior": null},
  "badges": ["suspicious"],
  "evaluatedAt": "2026-11-18T15:04:00Z"
}

matchedRule is null when the default verdict applied. index is the rule's position in the list, starting at 0. In dry_run the same body has "verdict": "allow" and "wouldBe": "deny".

A definition that does not validate is a 400 that names the problem: an unknown condition type, an operator other than the four above, a verdict other than allow, review, or deny, or a slug the team already uses (409).

When the Check Cannot Answer

Fail open or fail closed is your explicit choice. Make it for each gated action from how sensitive that action is. If Dregs cannot evaluate the gate, you decide. That includes an unknown gate (gate_not_found), an unknown identity (an empty 404, the same response as the other identity actions), HTTP 402 because the monthly operations quota is used up, any other error, a timeout, or Dregs being unreachable.

A sensitive action that grants value, such as granting trial credits, can fail closed: proceed only when the response is "verdict": "allow". review, deny, and every case where there is no verdict all stop the action.

A low-risk action can fail open: proceed when you do not get a verdict, and stop on deny. You can also stop on review when you want a person to look before that action continues.

review means a person should look. deny means the rules say the action should not happen. A brand-new user who is not tracked yet is an unknown identity, not a score_missing match. score_missing applies only after the identity exists. A check that is refused for the operations quota is not written to the check log, because no verdict was produced. Deleting an identity deletes its check rows as well.

Warnings

Create, update, and check responses include a warnings array. Each item has a code and a message. The array is empty when there is nothing to say. A score name other than humanity, authenticity, uniqueness, or behavior is a 400, not a warning. The codes are unknown_badge (the slug is not currently produced by a badge rule or enabled analyzer for this team; a check also counts a badge already on that identity, and saving a gate also counts a slug that is still active on some identity), score_not_caught (on a check, a referenced score is missing on this identity and no score_missing condition names it), and dry_run (the gate returns allow and puts the real verdict in wouldBe). The check-time and definition-time known-badge sets differ on purpose for a badge that is still active after its analyzer was paused: saving a gate counts it, and a check counts it only when that identity already has it.

The Check Log

Every check is stored: the identity, the gate, the verdict returned to you, the real verdict, the matched rule, the mode, the context you sent, and the time. GET /api/gate-checks lists them newest first. Filter with gate, identity, or both. Rows are kept for your plan's data retention period, and at least 90 days. A plan with no retention set keeps them for 90 days. A longer plan keeps them longer. A check refused because the operations quota is used up is not stored.

The same operations are available to an AI agent: list_gates, get_gate, create_gate, update_gate, delete_gate, check_gate, and list_gate_checks. Creating, updating, and deleting require an admin. See AI Agents and the API reference.