Skip to content

API Reference

Jump to bottom
Nick edited this page Nov 18, 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

Основной endpoint для анализа batch сообщений. Возвращает pattern groups с 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"
}

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
    }
  ],
  "export": "...",
  "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")

3. Ingest Messages

POST /api/v1/messages/ingest

Ингестировать сообщения в систему.

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

Запустить pattern mining на существующих сообщениях.

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

Получить список всех паттернов.

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

Получить список всех правил.

Query Parameters:

  • status (optional): Filter by rule status
  • limit (optional): Maximum number of rules to return

Response:

{
  "rules": [
    {
      "id": 1,
      "pattern_id": 1,
      "status": "active",
      "sql_expression": "...",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

7. Evaluate Shadow Rules

POST /api/v1/rules/eval-shadow

Оценить правила в 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

Продвинуть shadow rules в active.

Response:

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

9. Export Rules

GET /api/v1/rules/export

Экспортировать active rules.

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;
}

Error Handling

Все ошибки возвращаются в формате:

{
  "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

См. API Quickstart для примеров использования.

Last Updated: 2025-11-15

Clone this wiki locally