Skip to content
Last updated

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

Previous page
Next page