# Rules API

The Rules Management API provides comprehensive endpoints for creating, managing, and applying reusable behavior rules across multiple entity types within an organization. Rules support fine-grained access control, version tracking, public/private visibility, and flexible attachment configurations.

## Key Features

- **Rule Management**: Create, update, delete, and duplicate rules
- **Access Control**: Three-tier access system (owner, edit, view)
- **Attachments**: Attach rules to assistants, users, models, vector stores, and organizations
- **Priority System**: Control rule application order with 1-100 priority scale
- **Character Limits**: Set per-attachment character limits (100-50,000)
- **Public Rules**: Share rules across organizations
- **Statistics**: Track usage and category distribution
- **Version Tracking**: Automatic version incrementing on updates


## Entity Attachments

Rules can be attached to multiple entity types with independent configurations:

- **assistant** - Attach rules to specific AI assistants
- **user** - Attach rules to individual users
- **model** - Attach rules to specific AI models
- **vector_store** - Attach rules to vector stores for RAG contexts
- **organization** - Attach rules organization-wide


Each attachment supports:

- **Priority** (1-100) - Controls application order
- **Character Limit** (100-50,000) - Limits content length
- **Active Status** - Enable/disable without removing


## Priority System

Rules attached to entities use a priority-based application system:

- **Range**: 1-100 (higher numbers = higher priority)
- **Default**: 50 (standard priority)
- **Ordering**: Rules apply in descending priority order (highest first)
- **Use Cases**:
  - **90-100**: Critical/safety rules that must be applied first
  - **70-89**: High priority (compliance, security)
  - **50-69**: Standard priority (default range)
  - **30-49**: Low priority
  - **1-29**: Optional/supplementary rules


When multiple rules have the same priority, they are ordered by attachment timestamp.

## Rule Management

- `POST /v1/organizations/{organization_id}/rules` - Create a new rule
- `GET /v1/organizations/{organization_id}/rules` - List rules with filtering
- `GET /v1/organizations/{organization_id}/rules/{rule_id}` - Get rule details (org-scoped)
- `GET /v1/rules/{rule_id}` - Get rule details (global access)
- `PUT /v1/organizations/{organization_id}/rules/{rule_id}` - Update a rule
- `DELETE /v1/organizations/{organization_id}/rules/{rule_id}` - Delete a rule
- `POST /v1/organizations/{organization_id}/rules/{rule_id}/duplicate` - Duplicate a rule
- `GET /v1/organizations/{organization_id}/rules/public` - List public rules


## Statistics

- `GET /v1/rules/statistics/categories` - Category statistics
- `GET /v1/rules/{rule_id}/statistics/usage` - Usage statistics


## Rule Attachments

- `POST /v1/rules/{rule_id}/attachments` - Attach entity to rule
- `GET /v1/rules/{rule_id}/attachments` - List rule attachments
- `GET /v1/rules/{rule_id}/attachments/{entity_type}/{entity_id}` - Get specific attachment
- `PUT /v1/rules/{rule_id}/attachments/{entity_type}/{entity_id}` - Update attachment
- `DELETE /v1/rules/{rule_id}/attachments/{entity_type}/{entity_id}` - Detach entity
- `GET /v1/rules/entities/{entity_type}/{entity_id}/rules` - List rules for entity


## Access Rights

- `POST /v1/rules/{rule_id}/access` - Grant access to user
- `GET /v1/rules/{rule_id}/access` - List access rights
- `PUT /v1/rules/{rule_id}/access/{user_id}` - Update access level
- `DELETE /v1/rules/{rule_id}/access/{user_id}` - Revoke access


## Objects

- [Rule object](/docs/api-reference/objects/rule-object)