API Reference

Rules

Rules are policies evaluated by the Rule Engine against every incoming signal. When a rule's condition matches, the configured action is taken: block the request, log it, send a notification, or trigger a webhook.

The rule object

{
  "id":          "rule_7b3c1d9e",
  "name":        "Block GPT-4o for compliance",
  "type":        "model_filter",
  "enabled":     true,
  "scope":       "org",
  "scope_id":    "org_abc123",
  "priority":    10,
  "condition": {
    "model": { "in": ["gpt-4o", "gpt-4-turbo"] }
  },
  "action":      "block",
  "action_config": {
    "message": "GPT-4o is not approved for use in this organization."
  },
  "created_at":  "2025-04-01T00:00:00Z",
  "updated_at":  "2025-05-01T12:00:00Z"
}

Rule types

Type	Description
`budget`	Enforces a cumulative cost or token limit over a time window
`model_filter`	Allows or blocks specific models
`user_limit`	Applies per-user token or cost limits
`org_policy`	Org-wide policies (e.g., require project_id, block unknown models)

Scopes

Scope	Applies to
`user`	A single user
`team`	All users in a team
`org`	All users in the organization
`project`	A specific project_id

Actions

Action	Effect
`block`	The local agent rejects the emit; the tool call is aborted with a message
`warn`	Signal is accepted but a warning is surfaced in the dashboard
`log`	Signal is accepted and a rule_triggered event is logged silently
`notify`	Sends a notification (Slack, email, webhook) without blocking

Endpoints

List rules

GET /api/v1/rules

Get a rule

GET /api/v1/rules/:id

Create a rule

POST /api/v1/rules
Content-Type: application/json

{
  "name":     "Monthly $500 org budget",
  "type":     "budget",
  "scope":    "org",
  "scope_id": "org_abc123",
  "priority": 1,
  "condition": {
    "window":    "monthly",
    "metric":    "cost_usd",
    "threshold": 500
  },
  "action": "block"
}

Update a rule

PUT /api/v1/rules/:id
Content-Type: application/json

{
  "enabled": false
}

Partial updates are supported — only include fields you want to change.

Delete a rule

DELETE /api/v1/rules/:id

Returns 204 No Content on success.

Condition schema

Conditions vary by rule type:

// budget
{
  "window":    "daily" | "monthly",
  "metric":    "cost_usd" | "tokens_in" | "tokens_out" | "tokens_total",
  "threshold": number
}

// model_filter
{
  "model": {
    "in":     ["model-a", "model-b"],   // blocklist mode
    "not_in": ["model-a", "model-b"]    // allowlist mode (block others)
  }
}

// user_limit
{
  "window":    "daily" | "monthly",
  "metric":    "cost_usd" | "tokens_total",
  "per_user":  number
}

// org_policy
{
  "require_project_id": true,
  "block_unknown_models": true
}