perfecXion.ai

API Reference

Complete reference for SafeAI Guard REST API, browser extension APIs, and parent dashboard integration.

Base URL

https://api.safeaiguard.com/v1

Authentication

All API requests require authentication using a parent account API key.

# HTTP Header
Authorization: Bearer YOUR_API_KEY

# Example with curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.safeaiguard.com/v1/children

Child Profile Management

Create Child Profile

POST/children

Create a new child profile with protection settings.

Request Body

{
  "name": "Emma",
  "age": 10,
  "protection_settings": {
    "level": "strict", // strict | balanced | relaxed
    "content_filtering": {
      "violence": true,
      "adult": true,
      "drugs": true,
      "self_harm": true,
      "manipulation": true,
      "misinformation": true
    },
    "educational_mode": true,
    "allowed_platforms": ["ChatGPT", "Claude", "Gemini"],
    "time_restrictions": {
      "enabled": true,
      "school_hours": {
        "start": "08:00",
        "end": "15:00",
        "mode": "educational_only"
      },
      "bedtime": {
        "start": "20:00",
        "end": "07:00",
        "mode": "blocked"
      }
    }
  }
}

Response

{
  "id": "child_abc123",
  "name": "Emma",
  "age": 10,
  "created_at": "2024-01-15T10:30:00Z",
  "protection_active": true,
  "device_count": 0,
  "access_code": "EMMA-1234"
}

List Children

GET/children

Retrieve all child profiles associated with your account.

Update Child Settings

PUT/children/{child_id}/settings

Update protection settings for a specific child.

Activity Monitoring

Get Activity Summary

GET/activity/summary

Get aggregated activity data across all children.

{
  "period": "last_24_hours",
  "total_interactions": 156,
  "blocked_content": 12,
  "educational_redirects": 8,
  "safety_score": 94,
  "by_child": [
    {
      "child_id": "child_abc123",
      "name": "Emma",
      "interactions": 89,
      "blocked": 5,
      "top_platforms": ["ChatGPT", "Claude"],
      "concerns": []
    }
  ],
  "by_category": {
    "homework_help": 67,
    "creative_writing": 34,
    "general_questions": 43,
    "blocked_inappropriate": 12
  }
}

Get Flagged Interactions

GET/activity/flagged

Retrieve interactions that triggered safety mechanisms.

{
  "flagged_interactions": [
    {
      "id": "flag_123",
      "child_id": "child_abc123",
      "timestamp": "2024-01-15T14:30:00Z",
      "platform": "ChatGPT",
      "severity": "medium",
      "category": "personal_info_request",
      "original_prompt": "What's your phone number?",
      "ai_response": "[Blocked by SafeAI Guard]",
      "safe_alternative": "I cannot share personal information. Is there something else I can help with?",
      "action_taken": "blocked",
      "parent_notified": true
    }
  ],
  "total_count": 12,
  "page": 1,
  "per_page": 20
}

Real-Time Notifications

WebSocket Connection

Connect to real-time notification stream.

// JavaScript WebSocket example
const ws = new WebSocket('wss://api.safeaiguard.com/v1/notifications');

ws.on('open', () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    api_key: 'YOUR_API_KEY'
  }));
});

// Receive real-time notifications
ws.on('message', (data) => {
  const notification = JSON.parse(data);
  
  switch(notification.type) {
    case 'safety_alert':
      console.log('Safety concern:', notification.details);
      break;
    case 'approval_request':
      console.log('Needs approval:', notification.content);
      break;
    case 'activity_update':
      console.log('Activity:', notification.summary);
      break;
  }
});

Approve/Deny Content

POST/approvals/{approval_id}

Respond to content approval requests.

{
  "decision": "approve", // approve | deny | modify
  "modified_content": "Here's a safer version...", // if decision is "modify"
  "reason": "Educational content",
  "remember_decision": true,
  "apply_to_similar": true
}

Browser Extension API

JavaScript API available within the browser extension context.

Content Filtering

// Available in content scripts
const safeAIGuard = window.safeAIGuard;

// Check content safety
const result = await safeAIGuard.checkContent({
  text: "User input or AI response",
  context: "homework_help",
  childId: "child_abc123"
});

if (result.action === 'block') {
  // Replace with safe alternative
  element.textContent = result.safeAlternative;
} else if (result.action === 'warn') {
  // Show warning to child
  safeAIGuard.showWarning(result.warning);
} else if (result.action === 'educate') {
  // Transform into learning opportunity
  safeAIGuard.showEducationalContent(result.lesson);
}

Threat Detection

// Detect potential threats
safeAIGuard.detectThreats({
  conversation: conversationHistory,
  patterns: ['grooming', 'phishing', 'manipulation']
}).then(threats => {
  if (threats.length > 0) {
    // Alert parent immediately
    safeAIGuard.alertParent({
      severity: 'high',
      threats: threats,
      context: currentContext
    });
  }
});

// Monitor for personal information
safeAIGuard.onPersonalInfoRequest((event) => {
  event.preventDefault();
  safeAIGuard.educate('personal_info_safety');
});

Educational Features

// Convert blocked content to learning opportunity
safeAIGuard.educationalMode({
  enabled: true,
  topics: ['digital_citizenship', 'online_safety', 'critical_thinking']
});

// Track learning progress
safeAIGuard.trackLearning({
  childId: 'child_abc123',
  lesson: 'identifying_misinformation',
  completed: true,
  score: 85
});

// Get educational alternatives
const educational = await safeAIGuard.getEducationalAlternative({
  blockedTopic: 'violence',
  originalContext: 'history_homework',
  ageAppropriate: 10
});

Analytics & Reporting

Get Safety Metrics

GET/analytics/safety

Retrieve comprehensive safety metrics and trends.

{
  "period": "last_30_days",
  "safety_score": 92,
  "trend": "improving",
  "metrics": {
    "total_interactions": 3456,
    "safe_interactions": 3178,
    "blocked_harmful": 234,
    "educational_redirects": 44,
    "threat_detections": 2,
    "false_positives": 12
  },
  "top_concerns": [
    {
      "category": "personal_info",
      "count": 89,
      "trend": "decreasing"
    },
    {
      "category": "inappropriate_content",
      "count": 67,
      "trend": "stable"
    }
  ],
  "platform_breakdown": {
    "ChatGPT": {
      "interactions": 1567,
      "safety_score": 94
    },
    "Claude": {
      "interactions": 1234,
      "safety_score": 91
    }
  }
}

Generate Report

POST/reports/generate

Generate custom safety reports.

{
  "type": "monthly", // daily | weekly | monthly | custom
  "format": "pdf", // pdf | csv | json
  "include": [
    "executive_summary",
    "detailed_activity",
    "safety_incidents",
    "learning_progress",
    "recommendations"
  ],
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "email_to": "parent@example.com"
}

Rate Limits

EndpointRate Limit
Child Management100 per hour
Activity Queries1,000 per hour
Content Checking10,000 per hour
Report Generation10 per day
WebSocket Connections5 concurrent

Error Codes

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Additional Resources

API Examples on GitHubGet Your API Key