List Rules

Overview

Retrieves a paginated list of rules with support for filtering by status, category, entity type, tags, and search. Useful for displaying rule libraries, dashboards, and management interfaces.

Endpoint

GET http://api.gu1.ai/rules

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

page

number

default:"1"

Page number for pagination

pageSize

number

default:"20"

Number of rules per page (max: 100)

status

string

Filter by status: draft, active, shadow, archived, inactive

Response

rules

array

Array of rule objects

total

string

Total number of rules matching filters

page

number

Current page number

pageSize

number

Number of items per page

totalPages

number

Total number of pages

Example Requests

List All Active Rules

curl -X GET "http://api.gu1.ai/rules?status=active&enabled=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Rules

curl -X GET "http://api.gu1.ai/rules?search=sanctions&category=aml" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Entity Type and Risk Matrix

curl -X GET "http://api.gu1.ai/rules?targetEntityType=company&riskMatrixId=d257247b-af7b-402a-ad8f-eac209e2990e&pageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sort by Priority

curl -X GET "http://api.gu1.ai/rules?sortBy=priority&sortOrder=desc&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Tags

curl -X GET "http://api.gu1.ai/rules?tags=high-risk,pep" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "rules": [
    {
      "id": "e2cdd639-52cc-4749-9b16-927bfa5dfaea",
      "organizationId": "71e8f908-e032-4fcb-b0ce-ad0cd0ffb236",
      "name": "CNPJ Blocklist Check",
      "description": "Block companies with specific CNPJ",
      "category": "kyb",
      "status": "active",
      "enabled": true,
      "priority": 100,
      "score": 85,
      "targetEntityTypes": ["company"],
      "evaluationMode": "sync",
      "riskMatrixId": "d257247b-af7b-402a-ad8f-eac209e2990e",
      "version": 1,
      "tags": [],
      "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
      "createdAt": "2024-12-22T14:10:28.131Z",
      "updatedAt": "2024-12-22T14:44:29.627Z",
      "stats": {
        "failures": 0,
        "successes": 7,
        "executions": 7
      }
    },
    {
      "id": "a5a29ed9-1e98-4a57-8e89-3aa819d5da0a",
      "organizationId": "71e8f908-e032-4fcb-b0ce-ad0cd0ffb236",
      "name": "Terrorism Sanctions Check",
      "description": "Detect entities with terrorism-related sanctions",
      "category": "aml",
      "status": "active",
      "enabled": true,
      "priority": 100,
      "score": 95,
      "targetEntityTypes": ["person", "company"],
      "evaluationMode": "sync",
      "riskMatrixId": "b6d543cb-1006-4bbb-8777-c43859d51c8a",
      "version": 1,
      "tags": ["sanctions", "terrorism", "critical"],
      "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
      "createdAt": "2024-12-21T17:09:00.746Z",
      "updatedAt": "2024-12-22T14:41:32.821Z",
      "stats": {
        "failures": 12,
        "successes": 7,
        "executions": 19
      }
    }
  ],
  "total": "2",
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}

Pagination Example

async function getAllRules() {
  const allRules = [];
  let page = 1;
  const pageSize = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `http://api.gu1.ai/rules?page=${page}&pageSize=${pageSize}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const data = await response.json();
    allRules.push(...data.rules);

    hasMore = page < data.totalPages;
    page++;
  }

  return allRules;
}

// Usage
const rules = await getAllRules();
console.log(`Fetched ${rules.length} total rules`);

Use Cases

Build Rule Dashboard

async function buildRuleDashboard() {
  // Get active rules grouped by category
  const categories = ['kyc', 'kyb', 'aml', 'fraud', 'compliance'];
  const dashboard = {};

  for (const category of categories) {
    const response = await fetch(
      `http://api.gu1.ai/rules?category=${category}&status=active`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const data = await response.json();
    dashboard[category] = {
      total: parseInt(data.total),
      rules: data.rules.map(r => ({
        id: r.id,
        name: r.name,
        enabled: r.enabled,
        priority: r.priority,
        score: r.score,
        executions: r.stats.executions,
        successRate: (r.stats.successes / r.stats.executions * 100).toFixed(1) + '%'
      }))
    };
  }

  return dashboard;
}

Monitor High-Priority Rules

def monitor_high_priority_rules():
    """Monitor rules with priority >= 90"""
    response = requests.get(
        'http://api.gu1.ai/rules',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        },
        params={
            'sortBy': 'priority',
            'sortOrder': 'desc',
            'pageSize': 100
        }
    )

    data = response.json()
    high_priority = [r for r in data['rules'] if r['priority'] >= 90]

    print(f"Found {len(high_priority)} high-priority rules:\n")

    for rule in high_priority:
        status_icon = '✅' if rule['enabled'] else '❌'
        print(f"{status_icon} [{rule['priority']}] {rule['name']}")
        print(f"   Category: {rule['category']}")
        print(f"   Executions: {rule['stats']['executions']}")
        print(f"   Success Rate: {rule['stats']['successes'] / max(rule['stats']['executions'], 1) * 100:.1f}%")
        print()

    return high_priority

Find Rules by Risk Matrix

async function getRulesByMatrix(riskMatrixId) {
  const response = await fetch(
    `http://api.gu1.ai/rules?riskMatrixId=${riskMatrixId}&pageSize=100`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  return {
    matrixId: riskMatrixId,
    totalRules: parseInt(data.total),
    active: data.rules.filter(r => r.enabled).length,
    inactive: data.rules.filter(r => !r.enabled).length,
    byCategory: data.rules.reduce((acc, rule) => {
      acc[rule.category] = (acc[rule.category] || 0) + 1;
      return acc;
    }, {}),
    rules: data.rules
  };
}

Search and Filter

def search_rules(search_term, filters=None):
    """Advanced rule search with multiple filters"""
    params = {
        'search': search_term,
        'pageSize': 50
    }

    if filters:
        params.update(filters)

    response = requests.get(
        'http://api.gu1.ai/rules',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        },
        params=params
    )

    data = response.json()

    print(f"Search: '{search_term}'")
    if filters:
        print(f"Filters: {filters}")
    print(f"Results: {data['total']} rules found\n")

    for rule in data['rules']:
        print(f"- {rule['name']}")
        print(f"  Category: {rule['category']} | Status: {rule['status']}")
        print(f"  Score: {rule['score']} | Priority: {rule['priority']}")
        print()

    return data['rules']

# Example usage
search_rules('pep', {
    'category': 'aml',
    'status': 'active',
    'enabled': True
})

Export Rules for Backup

async function exportAllRules() {
  const response = await fetch(
    'http://api.gu1.ai/rules?pageSize=100',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  // Create backup object
  const backup = {
    exportDate: new Date().toISOString(),
    totalRules: parseInt(data.total),
    rules: data.rules.map(rule => ({
      name: rule.name,
      description: rule.description,
      category: rule.category,
      targetEntityTypes: rule.targetEntityTypes,
      conditions: rule.conditions,
      actions: rule.actions,
      priority: rule.priority,
      score: rule.score,
      evaluationMode: rule.evaluationMode,
      scope: rule.scope,
      tags: rule.tags
    }))
  };

  // Save to file (Node.js)
  const fs = require('fs');
  fs.writeFileSync(
    `rules-backup-${Date.now()}.json`,
    JSON.stringify(backup, null, 2)
  );

  console.log(`✅ Exported ${backup.totalRules} rules`);

  return backup;
}

Best Practices

Use Pagination: Always paginate when fetching large rule sets
Filter Efficiently: Combine filters to narrow results (category + status + enabled)
Cache Results: Cache frequently accessed rule lists
Sort Strategically: Sort by priority for execution order, by updatedAt for recent changes
Monitor Performance: Track rules with high failure rates using stats
Use Tags: Leverage tags for custom organization and filtering

Performance Notes

Default page size: 20 rules
Maximum page size: 100 rules
Average response time: 50-150ms
Search indexes: name, description
Filter indexes: status, category, enabled, targetEntityType, riskMatrixId

​Overview

​Endpoint

​Authentication

​Query Parameters

​Response

​Example Requests

​List All Active Rules

​Search Rules

​Filter by Entity Type and Risk Matrix

​Sort by Priority

​Filter by Tags

​Response Example

​Pagination Example

​Use Cases

​Build Rule Dashboard

​Monitor High-Priority Rules

​Find Rules by Risk Matrix

​Search and Filter

​Export Rules for Backup

​Best Practices

​Performance Notes

​See Also

Overview

Endpoint

Authentication

Query Parameters

Response

Example Requests

List All Active Rules

Search Rules

Filter by Entity Type and Risk Matrix

Sort by Priority

Filter by Tags

Response Example

Pagination Example

Use Cases

Build Rule Dashboard

Monitor High-Priority Rules

Find Rules by Risk Matrix

Search and Filter

Export Rules for Backup

Best Practices

Performance Notes

See Also