Veto/docs

Policies API

CRUD endpoints for managing tool policies — the rules that govern what tool calls are allowed.

Policies define the validation rules for each tool. Each policy is scoped to an organization and identified by tool name (one policy per tool).

All endpoints require authentication via API key (X-Veto-API-Key) or Bearer JWT with X-Organization-Id header.

List policies

GET /v1/policies

Returns all policies for the authenticated organization.

Response

{
  "data": [
    {
      "toolName": "transfer_funds",
      "version": 3,
      "isActive": true,
      "mode": "deterministic",
      "constraints": [
        {
          "argumentName": "amount",
          "enabled": true,
          "minimum": 0,
          "maximum": 10000,
          "required": true
        },
        {
          "argumentName": "currency",
          "enabled": true,
          "enum": ["USD", "EUR", "GBP"]
        }
      ],
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z"
    }
  ]
}

Get policy

GET /v1/policies/:toolName

Returns the policy for a specific tool, including the tool definition if registered.

Response

{
  "toolName": "transfer_funds",
  "version": 3,
  "isActive": true,
  "mode": "deterministic",
  "constraints": [
    {
      "argumentName": "amount",
      "enabled": true,
      "minimum": 0,
      "maximum": 10000,
      "required": true
    }
  ],
  "sessionConstraints": {
    "maxCalls": 5,
    "cumulativeLimits": [
      { "argumentName": "amount", "maxValue": 50000 }
    ]
  },
  "tool": {
    "name": "transfer_funds",
    "description": "Transfer money to an account",
    "arguments": [
      { "name": "amount", "type": "number", "required": true },
      { "name": "to", "type": "string", "required": true }
    ]
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

The SDK calls this endpoint to fetch and cache policies for client-side deterministic validation. See How Validation Works.

Error: not found

{
  "error": {
    "code": "not_found",
    "message": "Policy not found: transfer_funds"
  }
}

Create policy

POST /v1/policies

Body

{
  "toolName": "send_email",
  "mode": "deterministic",
  "constraints": [
    {
      "argumentName": "to",
      "enabled": true,
      "required": true,
      "regex": "^[^@]+@(company\\.com|partner\\.org)$"
    },
    {
      "argumentName": "body",
      "enabled": true,
      "maxLength": 5000
    }
  ]
}

LLM policy

{
  "toolName": "send_email",
  "mode": "llm",
  "llmConfig": {
    "description": "Only allow emails to verified contacts about business topics",
    "exceptions": ["Emergency notifications are always allowed"],
    "argumentInstructions": [
      {
        "argumentName": "body",
        "instruction": "Must not contain personally identifiable information"
      }
    ],
    "preferredModel": "anthropic"
  }
}

Session constraints

{
  "toolName": "delete_record",
  "mode": "deterministic",
  "constraints": [
    { "argumentName": "id", "enabled": true, "required": true }
  ],
  "sessionConstraints": {
    "maxCalls": 3,
    "cumulativeLimits": [
      { "argumentName": "count", "maxValue": 100 }
    ]
  }
}

Response: 201

{
  "toolName": "send_email",
  "version": 1,
  "isActive": true,
  "mode": "deterministic",
  "constraints": [...],
  "quality": { "valid": true, "score": 0.95, "issues": [] },
  "createdAt": "2025-01-20T14:30:00Z"
}

Error: 409 conflict

{
  "error": {
    "code": "policy_exists",
    "message": "Policy for tool 'send_email' already exists"
  }
}

Update policy

PUT /v1/policies/:toolName

Replaces the policy for a tool. Increments the version number. Invalidates the cached policy on all connected SDKs.

Body

Same schema as create, without toolName (taken from the URL).

{
  "mode": "deterministic",
  "constraints": [
    {
      "argumentName": "amount",
      "enabled": true,
      "minimum": 0,
      "maximum": 5000
    }
  ]
}

Response

{
  "toolName": "transfer_funds",
  "version": 4,
  "isActive": true,
  "mode": "deterministic",
  "constraints": [...],
  "quality": { "valid": true, "score": 0.9, "issues": [] },
  "updatedAt": "2025-01-21T09:00:00Z"
}

Delete policy

DELETE /v1/policies/:toolName

Removes the policy and invalidates any cached copies.

Response

{
  "success": true
}

Activate / deactivate

Toggle a policy without deleting it.

POST /v1/policies/:toolName/activate
POST /v1/policies/:toolName/deactivate

Response

{
  "success": true,
  "message": "Policy for 'transfer_funds' deactivated"
}

When deactivated, the policy is skipped during validation — tool calls pass through without checks.

Validate policy (dry run)

Check a policy configuration for quality issues before saving it.

POST /v1/policies/:toolName/validate

Body

Same schema as create/update.

Response

{
  "valid": true,
  "score": 0.95,
  "issues": []
}

Or with issues:

{
  "valid": false,
  "score": 0.4,
  "issues": [
    "Constraint on 'amount' has minimum > maximum",
    "LLM config description is empty"
  ]
}

Constraint fields

Each constraint in the constraints array targets one argument:

FieldTypeDescription
argumentNamestringThe tool argument this constraint applies to
enabledbooleanWhether this constraint is active
requiredboolean?Argument must be present
notNullboolean?Argument cannot be null
minimumnumber?Value must be ≥ threshold
maximumnumber?Value must be ≤ threshold
greaterThannumber?Value must be > threshold
lessThannumber?Value must be < threshold
greaterThanOrEqualnumber?Alias for minimum
lessThanOrEqualnumber?Alias for maximum
minLengthnumber?String must be at least N characters
maxLengthnumber?String must be at most N characters
enumstring[]?Value must exactly match one of the allowed strings
regexstring?Value must match the pattern (max 256 chars, ReDoS-safe)
minItemsnumber?Array must have at least N elements
maxItemsnumber?Array must have at most N elements

See Constraints Reference for detailed behavior and examples.

LLM config fields

FieldTypeDescription
descriptionstringNatural language policy the LLM evaluates against
exceptionsstring[]Conditions where the policy should not apply
argumentInstructionsarray?Per-argument instructions for the LLM
preferredModelstring?"openai", "anthropic", or "google"

Session constraint fields

FieldTypeDescription
maxCallsnumber?Maximum calls to this tool per session
cumulativeLimitsarray?Cap cumulative argument values across calls
cumulativeLimits[].argumentNamestringArgument to track
cumulativeLimits[].maxValuenumberMaximum cumulative value

POST /v1/validate

Core validation endpoint — validates a tool call against policies.

Policy Drafts API

Create, review, and approve policy drafts before they become active policies.

On this page

List policiesResponseGet policyResponseError: not foundCreate policyBodyLLM policySession constraintsResponse: 201Error: 409 conflictUpdate policyBodyResponseDelete policyResponseActivate / deactivateResponseValidate policy (dry run)BodyResponseConstraint fieldsLLM config fieldsSession constraint fields