Skip to main content
GET
http://api.gu1.ai
/
rules
/
{id}
Get Rule
curl --request GET \
  --url http://api.gu1.ai/rules/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "organizationId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "category": "<string>",
  "status": "<string>",
  "enabled": true,
  "priority": 123,
  "score": 123,
  "conditions": {},
  "conditionCode": "<string>",
  "actions": [
    {}
  ],
  "scope": {},
  "targetEntityTypes": [
    {}
  ],
  "evaluationMode": "<string>",
  "riskMatrixId": "<string>",
  "version": 123,
  "previousVersionId": "<string>",
  "tags": [
    {}
  ],
  "stats": {},
  "createdBy": "<string>",
  "createdAt": "<string>",
  "updatedBy": "<string>",
  "updatedAt": "<string>"
}

Overview

Retrieves complete information about a specific rule, including its conditions, actions, execution statistics, and version history.

Endpoint

GET http://api.gu1.ai/rules/{id}

Authentication

Requires a valid API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY

Path Parameters

id
string
required
UUID of the rule to retrieve

Response

id
string
UUID of the rule
organizationId
string
Your organization ID
name
string
Rule name
description
string
Rule description
category
string
Rule category (kyc, kyb, aml, fraud, compliance, custom)
status
string
Current status (draft, active, shadow, archived, inactive)
enabled
boolean
Whether the rule is enabled
priority
number
Rule priority (1-100)
score
number
Risk score assigned when rule matches
conditions
object
Complete condition structure with nested logic
conditionCode
string
JSON string representation of conditions (for storage)
actions
array
Array of actions to execute when rule matches
scope
object
Rule scope configuration (countries, entity types, temporal windows)
targetEntityTypes
array
Array of entity types the rule applies to
evaluationMode
string
Evaluation mode (sync or async)
riskMatrixId
string
Associated risk matrix UUID (if any)
version
number
Current version number
previousVersionId
string
UUID of the previous version (if any)
tags
array
Array of tags for organization
stats
object
Execution statistics (executions, successes, failures)
createdBy
string
User ID who created the rule
createdAt
string
ISO timestamp of creation
updatedBy
string
User ID who last updated the rule
updatedAt
string
ISO timestamp of last update

Example Requests

curl -X GET http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "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,
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "id": "cond-1766412627987-0",
        "type": "simple",
        "field": "enrichmentData.normalized.taxId",
        "value": "33.592.510/0001-54",
        "filters": [],
        "operator": "eq",
        "countryMetadata": {
          "reason": "Selected from BR enrichment fields",
          "confidence": 100,
          "countryCode": "BR",
          "manuallySet": true,
          "autoDetected": false
        }
      }
    ]
  },
  "conditionCode": "{\"operator\":\"AND\",\"conditions\":[{\"field\":\"enrichmentData.normalized.taxId\",\"operator\":\"eq\",\"value\":\"33.592.510/0001-54\",\"countryMetadata\":{\"countryCode\":\"BR\",\"autoDetected\":false,\"manuallySet\":true,\"confidence\":100,\"reason\":\"Selected from BR enrichment fields\"},\"filters\":[],\"id\":\"cond-1766412627987-0\",\"type\":\"simple\"}]}",
  "actions": [
    {
      "tags": ["blocklist", "high-priority"],
      "type": "createAlert",
      "createAlert": {
        "type": "COMPLIANCE",
        "title": "Blocklisted Company Detected",
        "severity": "CRITICAL",
        "recipients": ["compliance@company.com"],
        "description": "Company CNPJ found in blocklist"
      }
    },
    {
      "tags": [],
      "type": "updateEntityStatus",
      "updateEntityStatus": {
        "status": "blocked",
        "reason": "CNPJ in blocklist"
      }
    }
  ],
  "scope": {
    "type": "entity",
    "countries": ["BR"],
    "entityTypes": ["company"],
    "temporalWindow": {
      "days": 30,
      "hours": 24
    }
  },
  "targetEntityTypes": ["company"],
  "evaluationMode": "sync",
  "riskMatrixId": "d257247b-af7b-402a-ad8f-eac209e2990e",
  "version": 1,
  "previousVersionId": null,
  "abTest": null,
  "schedule": null,
  "tags": [],
  "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
  "createdAt": "2024-12-22T14:10:28.131Z",
  "updatedBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
  "updatedAt": "2024-12-22T14:44:29.627Z",
  "stats": {
    "failures": 0,
    "successes": 7,
    "executions": 7
  }
}

Error Responses

404 Not Found

{
  "error": "Rule not found",
  "id": "e2cdd639-52cc-4749-9b16-927bfa5dfaea"
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "Access denied",
  "message": "You don't have permission to view this rule"
}

Use Cases

Display Rule Details in UI

async function loadRuleDetails(ruleId) {
  const response = await fetch(
    `http://api.gu1.ai/rules/${ruleId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const rule = await response.json();

  return {
    id: rule.id,
    name: rule.name,
    description: rule.description,
    status: rule.status,
    enabled: rule.enabled,
    priority: rule.priority,
    score: rule.score,
    category: rule.category,
    lastUpdated: new Date(rule.updatedAt),
    performance: {
      executions: rule.stats.executions,
      successRate: (rule.stats.successes / rule.stats.executions * 100).toFixed(1) + '%',
      failureRate: (rule.stats.failures / rule.stats.executions * 100).toFixed(1) + '%'
    },
    conditions: rule.conditions,
    actions: rule.actions.map(a => ({
      type: a.type,
      details: a[a.type]
    }))
  };
}

Monitor Rule Performance

def monitor_rule_performance(rule_id):
    """Monitor rule execution statistics"""
    response = requests.get(
        f'http://api.gu1.ai/rules/{rule_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        }
    )

    rule = response.json()
    stats = rule['stats']

    total = stats['executions']
    if total == 0:
        print(f"Rule '{rule['name']}' has not been executed yet")
        return

    success_rate = (stats['successes'] / total) * 100
    failure_rate = (stats['failures'] / total) * 100

    print(f"Rule: {rule['name']}")
    print(f"Status: {rule['status']}")
    print(f"Enabled: {rule['enabled']}")
    print(f"\nPerformance:")
    print(f"  Total Executions: {total}")
    print(f"  Success Rate: {success_rate:.1f}%")
    print(f"  Failure Rate: {failure_rate:.1f}%")
    print(f"\nLast Updated: {rule['updatedAt']}")

    # Alert if failure rate is high
    if failure_rate > 10:
        print(f"\n⚠️  WARNING: High failure rate detected!")

    return rule

Clone Rule Configuration

async function cloneRule(sourceRuleId, newName) {
  // Get the source rule
  const response = await fetch(
    `http://api.gu1.ai/rules/${sourceRuleId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const sourceRule = await response.json();

  // Create new rule with modified name
  const newRule = {
    name: newName,
    description: `Cloned from: ${sourceRule.name}`,
    category: sourceRule.category,
    targetEntityTypes: sourceRule.targetEntityTypes,
    conditions: sourceRule.conditions,
    actions: sourceRule.actions,
    enabled: false, // Start disabled
    priority: sourceRule.priority,
    score: sourceRule.score,
    status: 'draft', // Start as draft
    evaluationMode: sourceRule.evaluationMode,
    scope: sourceRule.scope,
    tags: [...sourceRule.tags, 'cloned']
  };

  // Create the cloned rule
  const createResponse = await fetch(
    'http://api.gu1.ai/rules',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(newRule)
    }
  );

  const clonedRule = await createResponse.json();
  console.log('Rule cloned successfully:', clonedRule.id);

  return clonedRule;
}

Export Rule Configuration

import json

def export_rule_config(rule_id, output_file):
    """Export rule configuration to JSON file"""
    response = requests.get(
        f'http://api.gu1.ai/rules/{rule_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        }
    )

    rule = response.json()

    # Remove runtime fields
    export_data = {
        '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.get('scope'),
        'tags': rule.get('tags', [])
    }

    # Write to file
    with open(output_file, 'w') as f:
        json.dump(export_data, f, indent=2)

    print(f"βœ… Rule configuration exported to {output_file}")
    return export_data

Best Practices

  1. Cache Rule Data: Cache frequently accessed rules to reduce API calls
  2. Monitor Statistics: Regularly check stats object for performance insights
  3. Track Versions: Use version and previousVersionId for audit trails
  4. Check Status: Always verify enabled and status before execution
  5. Use Tags: Leverage tags for organization and filtering

See Also