Skip to main content
GET
http://api.gu1.ai
/
rules
List Rules
curl --request GET \
  --url http://api.gu1.ai/rules \
  --header 'Authorization: Bearer <token>'
{
  "rules": [
    {}
  ],
  "total": "<string>",
  "page": 123,
  "pageSize": 123,
  "totalPages": 123
}

​
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
​
category
string
Filter by category: kyc, kyb, aml, fraud, compliance, custom
​
enabled
boolean
Filter by enabled status: true or false
​
targetEntityType
string
Filter by entity type: person, company, transaction
​
riskMatrixId
string
Filter by risk matrix UUID
​
tags
string
Filter by tags (comma-separated): high-risk,pep,sanctions
​
search
string
Search in rule name and description
​
sortBy
string
default:"updatedAt"
Sort field: name, priority, createdAt, updatedAt, score
​
sortOrder
string
default:"desc"
Sort order: asc or desc

​
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

  1. Use Pagination: Always paginate when fetching large rule sets
  2. Filter Efficiently: Combine filters to narrow results (category + status + enabled)
  3. Cache Results: Cache frequently accessed rule lists
  4. Sort Strategically: Sort by priority for execution order, by updatedAt for recent changes
  5. Monitor Performance: Track rules with high failure rates using stats
  6. 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

​
See Also