opendunes
Your account · 4 min
Copy page ▾

Guardrails

Put rules and a budget on a set of keys.

  1. Write the rules.
  2. Create the guardrail.
  3. Assign it to your keys.
  4. Read what it stopped.

1. Write the rules

A guardrail is a set of rules you put on your keys. It binds only the keys it is assigned to: your other keys run as before. Each rule below is optional; a guardrail holds any mix of them.

RuleDoesYou send
budgeta cap in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, reset daily, weekly or monthlylimit, reset_interval
modelsonly these models runallowed_models
providersonly these providers serveallowed_providers
zero data retentiononly endpoints that keep nothing, per labenforce_zdr_anthropic, enforce_zdr_openai, enforce_zdr_google, enforce_zdr_xai, enforce_zdr_other: true
prompt injectionblocks known injection patternscontent_filter_builtins: an entry with slug regex-prompt-injection and action block
sensitive informationredacts or blocks personal datacontent_filter_builtins: one entry per kind, its slug and an action, redact or block
custom filtersyour own patterns, redacted or blockedcontent_filters: one entry per pattern, its pattern and an action, redact or block

Every guardrail also takes a name, which it needs, and a description. Every field: Guardrail rules.

The kinds of personal data a guardrail knows, each named by its slug:

slugFinds
emailan email address
phonea phone number
credit-carda card number
ip-addressan IP address
addressa street address
ssna US social security number
secretsan API keyAPI keyThe key you create and send with every request that calls a model.More on API keys → or token pasted into a prompt

redact replaces what it finds with a label, such as [PHONE], before the model reads the prompt. block refuses the request.

2. Create the guardrail

Souk Bot runs on its own key, named Souk Bot. Yacine wants it held to 2 000 DA a month, an illustrative budget, on one model, with phone numbers redacted before any model reads them.

Watch out

The guardrail routes take a management keyManagement keyThe key that runs your account through the API: the balance, the usage history, your keys, guardrails, observability. It never calls a model.More on API keys →, never an API key. Set OPENDUNES_MANAGEMENT_KEY to your management key in the terminal that runs this sample. An API key gets a 401. See API keys.

The sample creates the guardrail, finds the key named Souk Bot and assigns the guardrail to it.

import json
import os
import urllib.request

MANAGEMENT_KEY = os.environ["OPENDUNES_MANAGEMENT_KEY"]
base_url = "https://opendunes.com/v1"
model = "anthropic/claude-sonnet-4.5"
key_name = "Souk Bot"


def call(method, path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    request = urllib.request.Request(
        base_url + path,
        method=method,
        data=data,
        headers={
            "Authorization": "Bearer " + MANAGEMENT_KEY,
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)


guardrail = call("POST", "/guardrails", {
    "name": "Souk Bot, monthly",
    "limit": 2000,
    "reset_interval": "monthly",
    "allowed_models": [model],
    "content_filter_builtins": [{"slug": "phone", "action": "redact"}],
})["data"]
print("guardrail", guardrail["id"])

keys = call("GET", "/keys")["data"]
hashes = [k["hash"] for k in keys if k["name"] == key_name]
if not hashes:
    raise SystemExit("No key is named " + key_name + ".")

path = "/guardrails/" + guardrail["id"] + "/assignments/keys"
assigned = call("POST", path, {"key_hashes": hashes})
print("assigned", assigned["assigned_count"])

201, with the guardrail under data: its id and every rule as you set it. limit comes back in DA.

A day, a week and a month are UTC. The week starts on Monday.

3. Assign it to your keys

A guardrail binds nothing until a key is assigned to it. A key is named by its hash, which the list of your keys gives: GET /v1/keys, under a management key.

RouteDoes
POST /v1/guardrails/{id}/assignments/keysassigns the keys in key_hashes
POST /v1/guardrails/{id}/assignments/keys/removeunassigns the keys in key_hashes
GET /v1/guardrails/{id}/assignments/keysthis guardrail's keys
GET /v1/guardrails/assignments/keysevery assignment on your account

To change a rule, send only that rule to PATCH /v1/guardrails/{id}. DELETE /v1/guardrails/{id} removes the guardrail, and its keys run free of it. Every guardrail route is free.

A key can sit under several guardrails. Each rule then combines its own way.

RuleUnder several guardrails
models, providersthe lists intersect: only what every guardrail allows
filtersthey add up: every guardrail's filters run
budgeteach counts on its own; the first spent stops the key
Good to know

A key's own cap still holds under a guardrail. A request stops at whichever limit is spent first. See Limits.

4. Read what it stopped

StatusWhenThe body
403the guardrail's budget is spentmetadata.limit_source reads guardrail
403a rule blocked the request: a model or provider not allowed, a filter set to block, a prompt injectionthe message says which rule

A spent budget stops every key the guardrail is assigned to, until it resets or you raise limit.

JSON
{
  "error": {
    "code": 403,
    "message": "This guardrail has spent its budget.",
    "metadata": {
      "limit_source": "guardrail"
    }
  }
}

The message above is illustrative.

Don't

Don't retry a 403 as it stands: the same request meets the same rule.

Do

Do read the message, which names the rule. Then change the request, or change the guardrail with PATCH /v1/guardrails/{id}.

Errors

The guardrail routes answer these. The body says why.

StatusWhen
400the body is malformed: no name, a slug or an action it does not know, or a pattern that does not compile
401the key is missing, wrong, disabled or expired, or it is an API key
404no guardrail of yours has this id

What to do on each: Errors and retries.

Last modified on