Skip to content

API Reference

Jump to bottom
Nick edited this page Nov 21, 2025 · 5 revisions

PATAS API Reference

Complete API endpoint documentation for developers.

Base URL

http://localhost:8000/api/v1

For production deployments, replace with your PATAS server URL.

Authentication

PATAS API uses API keys for authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8000/api/v1/analyze

Endpoints

1. Health Check

GET /api/v1/health

Check API status.

Response:

{
  "status": "ok",
  "core_ready": true,
  "version": "2.0.0"
}

2. Batch Analysis

POST /api/v1/analyze

Main endpoint for batch message analysis. Returns pattern groups with SQL queries.

Request:

{
  "messages": [
    {
      "id": "msg_001",
      "text": "Buy now! http://spam.com",
      "is_spam": true,
      "meta": {
        "sender": "user123",
        "source": "chat456"
      }
    }
  ],
  "run_mining": true,
  "run_evaluation": true,
  "export_backend": "sql",
  "profile": "conservative",
  "min_precision": 0.95,
  "include_explanations": false,
  "group_by_pattern": false
}

New Parameters (v2.1):

  • profile (optional): Filter rules by aggressiveness profile
    • conservative: min_precision=0.95, max_coverage=0.05, max_ham_hits=5
    • balanced: min_precision=0.90, max_coverage=0.10, max_ham_hits=10
    • aggressive: min_precision=0.85, max_coverage=0.20, max_ham_hits=20
  • min_precision (optional): Explicit minimum precision threshold (0.0-1.0)
    • Takes priority over profile if both are specified
    • Default: 0.95 when profile=conservative is used
  • include_explanations (optional, default: false): Include human-readable rule explanations
  • group_by_pattern (optional, default: false): Group rules under their patterns

Response:

{
  "patterns": [
    {
      "id": 1,
      "type": "URL",
      "description": "URL pattern: http://spam.com",
      "group_size": 45,
      "sources_count": 3,
      "senders_count": 2,
      "similarity_reason": "Messages contain the same suspicious URL: http://spam.com",
      "example_report_ids": ["msg_001", "msg_002", "msg_003"],
      "bot_likelihood": 0.85,
      "sql_query": "SELECT id, message_content, sender, source FROM reports WHERE LOWER(message_content) LIKE '%http://spam.com%'"
    }
  ],
  "rules": [
    {
      "id": 1,
      "pattern_id": 1,
      "status": "candidate",
      "sql_expression": "SELECT id FROM messages WHERE text LIKE '%http://spam.com%'",
      "precision": 0.95,
      "coverage": 0.15,
      "hits_total": 100,
      "explanation": "This rule detects messages matching the pattern: 'URL pattern: http://spam.com'. This rule was created because messages with this pattern were frequently marked as spam (precision: 95.0%).",
      "risk_assessment": {
        "risk_level": "low",
        "risk_warnings": [],
        "false_positive_scenarios": []
      }
    }
  ],
  "export": "...",
  "system_info": {
    "how_it_works": "Rules are created based on spam frequency: patterns are detected when messages with similar content were frequently marked as spam (is_spam=true).",
    "rule_creation": "Rules are generated from patterns that appear frequently in spam messages. Each rule is evaluated on historical data to measure precision, recall, and coverage."
  },
  "meta": {
    "ingested_count": 10,
    "patterns_created": 3,
    "rules_created": 3,
    "evaluation_count": 3,
    "timings": {
      "ingest_seconds": 0.123,
      "mining_seconds": 2.456,
      "evaluation_seconds": 0.789,
      "total_seconds": 3.368
    }
  }
}

Parameters:

  • messages (required): Array of message objects
  • run_mining (optional, default: true): Run pattern mining
  • run_evaluation (optional, default: true): Evaluate rules
  • export_backend (optional): Export format ("sql" or "rol")
  • profile (optional, v2.1): Filter rules by aggressiveness profile
  • min_precision (optional, v2.1): Explicit minimum precision threshold
  • include_explanations (optional, v2.1, default: false): Include rule explanations
  • group_by_pattern (optional, v2.1, default: false): Group rules under patterns

3. Ingest Messages

POST /api/v1/messages/ingest

Ingest messages into the system.

Request:

[
  {
    "id": "msg_001",
    "text": "Spam message",
    "is_spam": true,
    "meta": {}
  }
]

Response:

{
  "ingested_count": 1,
  "last_id": "msg_001"
}

4. Mine Patterns

POST /api/v1/patterns/mine

Run pattern mining on existing messages.

Request:

{
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-07T00:00:00Z"
}

Response:

{
  "patterns_created": 5,
  "rules_created": 5
}

5. List Patterns

GET /api/v1/patterns

Get list of all patterns.

Query Parameters:

  • limit (optional): Maximum number of patterns to return
  • type (optional): Filter by pattern type

Response:

{
  "patterns": [
    {
      "id": 1,
      "type": "URL",
      "description": "...",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

6. List Rules

GET /api/v1/rules

Get list of all rules with optional filtering, explanations, and risk assessment.

Query Parameters:

  • status (optional): Filter by rule status (candidate, shadow, active, deprecated)
  • limit (optional, default: 100): Maximum number of rules to return
  • offset (optional, default: 0): Pagination offset
  • include_evaluation (optional, default: false): Include evaluation metrics
  • profile (optional, v2.1): Filter by aggressiveness profile (conservative, balanced, aggressive)
  • min_precision (optional, v2.1): Explicit minimum precision threshold (0.0-1.0)
  • include_explanations (optional, v2.1, default: false): Include rule explanations
  • sort_by (optional, v2.1, default: "id"): Sort by field (id, precision, coverage, created_at)
  • deduplicate (optional, v2.1, default: false): Remove duplicate rules by SQL expression

Response:

[
  {
    "id": 1,
    "pattern_id": 1,
    "status": "active",
    "sql_expression": "SELECT id FROM messages WHERE text LIKE '%spam%'",
    "created_at": "2025-01-01T00:00:00Z",
    "evaluation": {
      "hits_total": 100,
      "spam_hits": 95,
      "ham_hits": 5,
      "precision": 0.95,
      "coverage": 0.15
    },
    "explanation": "This rule detects messages matching the pattern: 'Spam keyword pattern'. This rule was created because messages with this pattern were frequently marked as spam (precision: 95.0%).",
    "risk_assessment": {
      "risk_level": "low",
      "risk_warnings": [],
      "false_positive_scenarios": []
    }
  }
]

7. Evaluate Shadow Rules

POST /api/v1/rules/eval-shadow

Evaluate rules in shadow mode.

Request:

{
  "rule_ids": [1, 2, 3],
  "days": 7
}

Response:

{
  "evaluated_count": 3,
  "evaluations": [
    {
      "rule_id": 1,
      "hits_total": 100,
      "spam_hits": 95,
      "ham_hits": 5,
      "precision": 0.95,
      "coverage": 0.15
    }
  ]
}

8. Promote Rules

POST /api/v1/rules/promote

Promote shadow rules to active status based on evaluation metrics.

Response:

{
  "promoted_count": 2,
  "promoted_rules": [1, 2]
}

9. Export Rules

GET /api/v1/rules/export

Export active rules in specified format.

Query Parameters:

  • backend (required): Export format ("sql" or "rol")

Response:

  • For SQL: Plain text SQL script
  • For ROL: JSON object

Data Models

Message

interface Message {
  id: string;              // Unique message identifier
  text: string;             // Message text content
  is_spam?: boolean;        // Spam label (if available)
  meta?: {                  // Additional metadata
    sender?: string;
    source?: string;
    country?: string;
    has_media?: boolean;
    [key: string]: any;
  };
}

Pattern

interface Pattern {
  id: number;
  type: "URL" | "KEYWORD" | "SIGNATURE" | "TEXT";
  description: string;
  group_size: number;
  sources_count: number;
  senders_count: number;
  similarity_reason: string;
  example_report_ids: string[];
  bot_likelihood?: number;
  sql_query: string;
}

Rule

interface Rule {
  id: number;
  pattern_id?: number;
  status: "candidate" | "shadow" | "active" | "deprecated";
  sql_expression: string;
  precision?: number;
  coverage?: number;
  hits_total?: number;
  explanation?: string;  // v2.1: Human-readable explanation
  risk_assessment?: {   // v2.1: Risk assessment
    risk_level: "low" | "medium" | "high" | "unknown";
    risk_warnings: string[];
    false_positive_scenarios: string[];
  };
}

Error Handling

All errors are returned in the following format:

{
  "detail": "Error message"
}

HTTP Status Codes:

  • 200 - Success
  • 400 - Bad Request
  • 401 - Unauthorized
  • 404 - Not Found
  • 500 - Internal Server Error

Rate Limits

  • Free tier: 100 requests/hour
  • Pro tier: 1000 requests/hour
  • Enterprise: Unlimited

Examples

See API Quickstart for usage examples.

API Enhancements v2.1

New features added in v2.1:

  • Rule Filtering: Filter rules by precision threshold and aggressiveness profile
  • Rule Explanations: Optional human-readable explanations for rules
  • Risk Assessment: Automatic detection of false positive risks
  • Rule Organization: Grouping, sorting, and deduplication
  • System Information: Added system_info to responses

See API Enhancements v2.1 for complete documentation.

Last Updated: 2025-01-20

Clone this wiki locally