Documentation

API Reference

Complete reference for perfecX Comply REST API endpoints and SDK methods.

Base URL

https://api.perfecxion.ai/v1/comply

Authentication

All API requests require authentication using an API key and organization ID.

# HTTP Headers
X-API-Key: YOUR_API_KEY
X-Organization-ID: YOUR_ORG_ID

# Example with curl
curl -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Organization-ID: YOUR_ORG_ID" \
     https://api.perfecxion.ai/v1/comply/models

Model Management

Register Model

POST/models

Request Body

{
  "model_id": "customer-churn-v2",
  "name": "Customer Churn Predictor",
  "version": "2.0.0",
  "type": "classification",
  "purpose": "Predict customer churn probability",
  "deployment_env": "production",
  "data_categories": [
    "customer_demographics",
    "transaction_history",
    "support_interactions"
  ],
  "sensitive_features": ["age", "gender", "location"],
  "training_data": {
    "size": 1000000,
    "date_range": "2023-01-01 to 2023-12-31",
    "source": "customer_database"
  },
  "performance_metrics": {
    "accuracy": 0.89,
    "precision": 0.87,
    "recall": 0.91,
    "f1_score": 0.89
  },
  "metadata": {
    "team": "data-science",
    "owner": "john.doe@company.com",
    "framework": "tensorflow",
    "tags": ["customer-retention", "ml-ops"]
  }
}

Response

{
  "model_id": "customer-churn-v2",
  "compliance_id": "cmp_1234567890abcdef",
  "status": "registered",
  "risk_score": 45,
  "risk_level": "medium",
  "compliance_score": 78,
  "next_assessment": "2024-02-01T00:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

List Models

GET/models

Retrieve a list of all registered models.

Query Parameters

status - Filter by compliance status (compliant, non_compliant, pending)
risk_level - Filter by risk level (low, medium, high, critical)
framework - Filter by compliance framework
deployment_env - Filter by environment (production, staging, development)
limit - Number of results per page (default: 20, max: 100)
offset - Pagination offset

Update Model

PUT/models/{model_id}

Update model information and trigger re-assessment.

Delete Model

DELETE/models/{model_id}

Remove a model from compliance tracking.

Compliance Assessment

Run Compliance Assessment

POST/models/{model_id}/assess

Run a comprehensive compliance assessment on a model.

{
  "frameworks": ["EU_AI_ACT", "NIST_AI_RMF"],
  "include_bias_testing": true,
  "include_fairness_metrics": true,
  "include_explainability": true,
  "test_data": {
    "source": "s3://bucket/test-data.csv",
    "protected_attributes": ["gender", "race", "age"]
  }
}

Get Assessment Results

GET/models/{model_id}/assessments/{assessment_id}

Retrieve detailed assessment results.

{
  "assessment_id": "asmt_xyz789",
  "model_id": "customer-churn-v2",
  "status": "completed",
  "overall_score": 82,
  "risk_score": 35,
  "frameworks": {
    "EU_AI_ACT": {
      "compliant": true,
      "score": 85,
      "violations": [],
      "recommendations": [
        "Add model card documentation",
        "Implement user opt-out mechanism"
      ]
    },
    "NIST_AI_RMF": {
      "compliant": true,
      "score": 79,
      "violations": [
        {
          "code": "NIST-4.2.1",
          "severity": "low",
          "description": "Missing continuous monitoring plan"
        }
      ]
    }
  },
  "bias_metrics": {
    "demographic_parity": 0.03,
    "equal_opportunity": 0.02,
    "disparate_impact": 0.95
  },
  "completed_at": "2024-01-15T11:00:00Z"
}

Policy Management

Create Policy Set

POST/policies

Create a new compliance policy set.

{
  "name": "Production AI Governance",
  "description": "Comprehensive governance for production AI models",
  "rules": [
    {
      "type": "bias_threshold",
      "config": {
        "max_demographic_parity": 0.05,
        "max_equal_opportunity_diff": 0.05,
        "protected_attributes": ["gender", "race", "age"],
        "action": "block_deployment"
      }
    },
    {
      "type": "documentation_required",
      "config": {
        "required_docs": ["model_card", "risk_assessment", "bias_report"],
        "update_frequency": "monthly"
      }
    },
    {
      "type": "drift_detection",
      "config": {
        "threshold": 0.1,
        "check_frequency": "weekly",
        "metrics": ["accuracy", "feature_distribution"],
        "auto_retrain": true
      }
    },
    {
      "type": "data_privacy",
      "config": {
        "require_anonymization": true,
        "pii_detection": true,
        "retention_days": 90,
        "encryption_required": true
      }
    }
  ],
  "applies_to": {
    "deployment_env": ["production"],
    "risk_level": ["medium", "high", "critical"]
  }
}

Apply Policy to Models

POST/policies/{policy_id}/apply

Apply a policy set to specific models.

Reporting & Analytics

Generate Compliance Report

POST/reports

Generate comprehensive compliance reports.

{
  "type": "compliance_audit",
  "framework": "EU_AI_ACT",
  "format": "pdf",
  "include_sections": [
    "executive_summary",
    "model_inventory",
    "risk_assessment",
    "compliance_status",
    "violations",
    "recommendations",
    "evidence"
  ],
  "filters": {
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "models": ["production/*"],
    "include_archived": false
  },
  "branding": {
    "logo_url": "https://company.com/logo.png",
    "company_name": "Your Company Inc."
  }
}

Get Compliance Metrics

GET/metrics

Retrieve organization-wide compliance metrics.

{
  "organization_id": "org_123",
  "period": "last_30_days",
  "summary": {
    "total_models": 45,
    "compliant_models": 38,
    "compliance_rate": 0.844,
    "average_risk_score": 42.3,
    "critical_violations": 2,
    "pending_assessments": 5
  },
  "by_framework": {
    "EU_AI_ACT": {
      "compliant": 35,
      "non_compliant": 10,
      "average_score": 78.5
    },
    "NIST_AI_RMF": {
      "compliant": 40,
      "non_compliant": 5,
      "average_score": 82.1
    }
  },
  "by_risk_level": {
    "low": 20,
    "medium": 18,
    "high": 5,
    "critical": 2
  },
  "trends": {
    "compliance_rate": [
      {"date": "2024-01-01", "value": 0.80},
      {"date": "2024-01-08", "value": 0.82},
      {"date": "2024-01-15", "value": 0.844}
    ]
  }
}

Webhooks

Configure webhooks to receive real-time notifications about compliance events.

POST /webhooks

{
  "url": "https://your-domain.com/webhooks/compliance",
  "events": [
    "model.registered",
    "assessment.completed",
    "violation.detected",
    "policy.violated",
    "risk.elevated"
  ],
  "secret": "your-webhook-secret"
}

Webhook Payload Example

{
  "event": "violation.detected",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "model_id": "customer-churn-v2",
    "violation": {
      "type": "bias_threshold_exceeded",
      "severity": "high",
      "framework": "EU_AI_ACT",
      "details": {
        "metric": "demographic_parity",
        "threshold": 0.05,
        "actual": 0.08,
        "protected_attribute": "gender"
      }
    },
    "action_required": "immediate_review"
  }
}

Rate Limits

Endpoint	Rate Limit
Model Registration	100 per hour
Compliance Assessment	50 per hour
Report Generation	10 per hour
Metrics Retrieval	1,000 per hour
Policy Management	100 per hour

Error Codes

Code	Description
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
409	Conflict - Resource already exists
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

SDK Documentation

Python SDK Documentation Node.js SDK Documentation