VecTrail CRUD Logger API Documentation

⚡

Quick Start

Transform your database operations into intelligent, searchable stories in just one API call

# Single operation logging ✨
curl -X POST "http://localhost:3001/api/crud-logger/log" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "operation": "create",
    "tableName": "users", 
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "developer"
    },
    "metadata": {
      "connectionId": "64f9b8c7d4e5f6a7b8c9d0e1"
    }
  }'

# ✅ Auto-generates: "New user 'John Doe' was created on 9/11/2025, 2:30:45 PM with role: developer"

🎯

Smart Message Generation

Automatically converts your raw data into human-readable stories perfect for AI search and analytics

🔗

API Endpoints

POST /api/crud-logger/log

Single Log

Log a single CRUD operation with automatic intelligent message generation

Perfect for real-time operation tracking

POST /api/crud-logger/log-batch

Batch Processing

Log multiple CRUD operations efficiently (up to 100 operations)

Ideal for bulk data migrations and imports

POST /api/crud-logger/search

AI Search

Search through logged operations using vector similarity and natural language

RAG-powered intelligent search capabilities

GET /api/crud-logger/stats

Analytics

Get comprehensive usage statistics and insights for your logged operations

Perfect for monitoring and reporting

📋 Request Parameters

Single Log Operation (POST /log)

Parameter	Type	Required	Description
operation	string	✅	CRUD operation: "create", "read", "update", "delete"
tableName	string	✅	Name of the database table
data	object	❌	Data being operated on
recordId	string/number	❌	ID of the record being operated on
metadata	object	❌	Additional metadata (connectionId, etc.)
customMessage	string	❌	Custom human-readable message (overrides auto-generation)

Search Operations (POST /search)

Parameter	Type	Required	Description
query	string	✅	Search query for semantic search
limit	number	❌	Number of results to return (default: 10)
filters	object	❌	Additional filters (operation, tableName, etc.)
includeMetadata	boolean	❌	Include metadata in response (default: true)

💻 Code Examples

JavaScript / Node.js (axios)

const axios = require('axios');

// Log a user creation
async function logUserCreation(userData) {
  try {
    const response = await axios.post('http://localhost:3001/api/crud-logger/log', {
      operation: 'create',
      tableName: 'users',
      data: userData,
      metadata: {
        connectionId: '64f9b8c7d4e5f6a7b8c9d0e1',
        source: 'user-registration'
      }
    }, {
      headers: {
        'Authorization': `Bearer ${YOUR_JWT_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Log created:', response.data);
    // Output: User "John Doe" was created on 9/11/2025, 2:30:45 PM with role: developer
  } catch (error) {
    console.error('Logging failed:', error.response?.data);
  }
}

// Search logs
async function searchLogs(searchQuery) {
  try {
    const response = await axios.post('http://localhost:3001/api/crud-logger/search', {
      query: searchQuery,
      limit: 20,
      filters: {
        operation: 'create',
        tableName: 'users'
      }
    }, {
      headers: {
        'Authorization': `Bearer ${YOUR_JWT_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Search results:', response.data.results);
  } catch (error) {
    console.error('Search failed:', error.response?.data);
  }
}

Python (requests)

import requests
import json

def log_crud_operation(operation, table_name, data, jwt_token, metadata=None):
    """Log a CRUD operation to VecTrail"""
    url = "http://localhost:3001/api/crud-logger/log"
    
    payload = {
        "operation": operation,
        "tableName": table_name,
        "data": data,
        "metadata": metadata or {}
    }
    
    headers = {
        "Authorization": f"Bearer {jwt_token}",
        "Content-Type": "application/json"
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        
        result = response.json()
        print(f"✅ Logged: {result['humanMessage']}")
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"❌ Logging failed: {e}")
        return None

# Example usage
user_data = {
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "department": "Engineering"
}

log_crud_operation(
    operation="create",
    table_name="employees", 
    data=user_data,
    jwt_token="your-jwt-token-here",
    metadata={"source": "hr-system"}
)

PHP (cURL)

<?php

function logCrudOperation($operation, $tableName, $data, $jwtToken, $metadata = []) {
    $url = "http://localhost:3001/api/crud-logger/log";
    
    $payload = [
        'operation' => $operation,
        'tableName' => $tableName,
        'data' => $data,
        'metadata' => $metadata
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $jwtToken
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 201) {
        $result = json_decode($response, true);
        echo "✅ Logged: " . $result['humanMessage'] . "\n";
        return $result;
    } else {
        echo "❌ Logging failed: " . $response . "\n";
        return null;
    }
}

// Example usage
$productData = [
    'name' => 'Wireless Headphones',
    'price' => 99.99,
    'category' => 'Electronics'
];

logCrudOperation('create', 'products', $productData, 'your-jwt-token');
?>

🤖 Auto-Generated Message Examples

The CRUD Logger automatically generates human-readable messages based on your operation type and data. Here are some examples:

CREATE Operation

Input: { operation: "create", tableName: "users", data: { name: "John Doe", email: "john@example.com", role: "developer" } }
Generated: "New user 'John Doe' was created on 9/11/2025, 2:30:45 PM with role: developer"

UPDATE Operation

Input: { operation: "update", tableName: "products", data: { name: "iPhone 15", price: 999 }, recordId: "123" }
Generated: "Product 'iPhone 15' was updated on 9/11/2025, 2:30:45 PM - updated name, price"

DELETE Operation

Input: { operation: "delete", tableName: "orders", data: { orderId: "ORD-123" } }
Generated: "Order 'ORD-123' was deleted on 9/11/2025, 2:30:45 PM"

READ Operation

Input: { operation: "read", tableName: "customers", data: { status: "active", location: "NYC" } }
Generated: "Customer records were queried on 9/11/2025, 2:30:45 PM with criteria: status=active, location=NYC"

🎮 Interactive Demo

Try It Out

JWT Token

Operation

Table Name

Data (JSON)

Response

Response will appear here...

🎯 Use Cases

📊 Analytics & Reporting

Track user behavior, database changes, and system activities for business intelligence.

🔍 Audit Trails

Maintain detailed logs of who did what and when for compliance and security.

🤖 AI-Powered Insights

Use vector search to find patterns and trends in your operational data.

💬 Chatbot Integration

Power conversational interfaces with contextual information from your logs.

🚨 Debugging & Monitoring

Quickly search and identify issues in your application's data flow.

📈 User Journey Tracking

Understand user interactions and optimize their experience.

🔐 Authentication

All CRUD Logger API endpoints require JWT authentication:

Authorization: Bearer YOUR_JWT_TOKEN

Note: Each user can only access their own logs. The system automatically filters results by user ID for security.

🚀 Ready to start logging your CRUD operations intelligently?
Made with ❤️ for developers who love clean, searchable data

📝 CRUD Logger API