/ Documentation

Audit API

Comprehensive audit trail management and compliance monitoring. Track all system activities, generate compliance reports, and maintain detailed forensic records for regulatory requirements.

ComplianceAudit TrailsForensicsRegulatory

Base URL

https://sapienstream.com/api/audit

Overview

The Audit API provides comprehensive audit and compliance capabilities:

• Maintain immutable audit trails for all system activities
• Generate compliance reports for regulatory frameworks
• Perform forensic analysis and investigation workflows
• Monitor data integrity and change management
• Track user activities and access patterns
• Automate compliance monitoring and alerting

Endpoints Overview

GET/v1/audit/entries

Get audit entries

GET/v1/audit/entries/{id}

Get audit entry details

POST/v1/audit/entries

Create audit entry

GET/v1/audit/compliance

Get compliance status

POST/v1/audit/reports

Generate audit report

GET/v1/audit/investigations

List investigations

POST/v1/audit/investigations

Create investigation

Get Audit Entries

GET/v1/audit/entries

Retrieve audit trail entries with advanced filtering and search capabilities

Query Parameters

Parameter	Type	Description
`start_time`	string	Start time filter (ISO 8601)
`end_time`	string	End time filter (ISO 8601)
`event_type`	enum	login, logout, data_change, system_event, security_event
`user_id`	string	Filter by user identifier
`resource_type`	string	Filter by resource type (tag, machine, component)
`severity`	enum	low, medium, high, critical
`compliance_framework`	string	Filter by compliance framework (FDA_21CFR11, SOX, GDPR)

Example Request

curl -H "Authorization: Bearer sk_live_abc123..." \
     "https://sapienstream.com/api/audit/entries?start_time=2025-08-20T00:00:00Z&event_type=data_change&severity=high&limit=50"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "audit_entry_20250826_001234",
      "timestamp": "2025-08-26T14:25:30.789Z",
      "event_type": "data_change",
      "category": "configuration_change",
      "severity": "high",
      "user": {
        "user_id": "user_engineer_001",
        "username": "j.smith",
        "role": "process_engineer",
        "department": "production",
        "session_id": "session_abc123def456"
      },
      "resource": {
        "resource_type": "tag",
        "resource_id": "tag_temp_reactor_001", 
        "resource_name": "Reactor Temperature Sensor 01",
        "parent_machine": "machine_reactor_001"
      },
      "action": {
        "operation": "update_alarm_limits",
        "method": "PUT",
        "endpoint": "/v1/tags/tag_temp_reactor_001",
        "changes": [
          {
            "field": "alarm_high",
            "old_value": 180.0,
            "new_value": 190.0,
            "change_reason": "Process optimization - approved by engineering"
          }
        ]
      },
      "context": {
        "source_ip": "192.168.1.45",
        "user_agent": "SapienStream-WebUI/2.1.0",
        "location": "Plant A Control Room",
        "approval_reference": "change_request_CR-2025-08-001",
        "business_justification": "Increase temperature limit to support new product grade"
      },
      "compliance": {
        "frameworks": ["FDA_21CFR11", "ISO_27001"],
        "electronic_signature": {
          "required": true,
          "provided": true,
          "signature_id": "esig_20250826_001",
          "signature_meaning": "approved_and_implemented"
        },
        "data_integrity": {
          "hash": "sha256:a1b2c3d4e5f6...",
          "tamper_evident": true,
          "verified": true
        }
      },
      "impact_assessment": {
        "safety_impact": "low",
        "operational_impact": "medium",
        "compliance_impact": "high",
        "affected_systems": ["reactor_control_system"],
        "downstream_effects": ["alarm_management_system"]
      },
      "retention": {
        "retention_period": "7_years",
        "regulatory_requirement": "FDA_21CFR11",
        "archive_date": "2032-08-26T14:25:30.789Z",
        "immutable": true
      },
      "created_at": "2025-08-26T14:25:30.789Z",
      "checksum": "abc123def456789..."
    }
  ],
  "pagination": {
    "total": 12847,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_audit_entries_abc123",
    "query_execution_time_ms": 234,
    "data_sources": ["primary_audit_db", "compliance_archive"]
  }
}

Create Audit Entry

POST/v1/audit/entries

Create a new audit trail entry for manual logging or external system integration

Request Body Schema

Field	Type	Required	Description
`event_type`	enum	✓	Type of audit event
`severity`	enum	✓	Event severity level
`description`	string	✓	Event description
`resource_id`	string		Related resource identifier
`user_id`	string		User performing the action
`context`	object		Additional context information

Example Request

curl -X POST \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "security_event",
    "category": "unauthorized_access_attempt",
    "severity": "high",
    "description": "Multiple failed login attempts detected from external IP",
    "context": {
      "source_ip": "203.0.113.45",
      "attempted_username": "admin",
      "failure_count": 5,
      "time_window": "300_seconds",
      "detection_system": "security_monitor_v2.1"
    },
    "compliance_frameworks": ["ISO_27001", "NIST_CSF"],
    "requires_investigation": true,
    "auto_response": {
      "ip_blocked": true,
      "admin_notified": true,
      "security_team_alerted": true
    }
  }' \
  https://sapienstream.com/api/audit/entries

Example Response

{
  "success": true,
  "data": {
    "id": "audit_entry_20250826_001235",
    "timestamp": "2025-08-26T14:30:45.789Z",
    "event_type": "security_event",
    "category": "unauthorized_access_attempt",
    "severity": "high",
    "description": "Multiple failed login attempts detected from external IP",
    "status": "active",
    "context": {
      "source_ip": "203.0.113.45",
      "attempted_username": "admin",
      "failure_count": 5,
      "time_window": "300_seconds",
      "detection_system": "security_monitor_v2.1"
    },
    "compliance": {
      "frameworks": ["ISO_27001", "NIST_CSF"],
      "data_integrity": {
        "hash": "sha256:f7e8d9c0b1a2...",
        "tamper_evident": true,
        "verified": true
      },
      "retention_period": "7_years"
    },
    "investigation": {
      "auto_created": true,
      "investigation_id": "inv_security_20250826_001",
      "priority": "high",
      "assigned_to": "security_team"
    },
    "response_actions": {
      "ip_blocked": true,
      "notifications_sent": 3,
      "escalation_triggered": true
    },
    "created_at": "2025-08-26T14:30:45.789Z",
    "immutable": true,
    "checksum": "def456ghi789abc..."
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_create_audit_abc123"
  }
}

Compliance Status

GET/v1/audit/compliance

Get comprehensive compliance status across multiple regulatory frameworks

Example Request

curl -H "Authorization: Bearer sk_live_abc123..." \
     "https://sapienstream.com/api/audit/compliance?framework=FDA_21CFR11&period=current_year&include_details=true"

Example Response

{
  "success": true,
  "data": {
    "compliance_assessment": {
      "overall_score": 94.7,
      "status": "compliant",
      "last_assessment": "2025-08-26T14:00:00Z",
      "next_assessment": "2025-09-26T14:00:00Z"
    },
    "frameworks": [
      {
        "framework": "FDA_21CFR11",
        "compliance_score": 96.2,
        "status": "compliant",
        "requirements": {
          "total": 45,
          "compliant": 43,
          "partial": 2,
          "non_compliant": 0
        },
        "key_metrics": {
          "electronic_signatures": {
            "required": 1247,
            "provided": 1247,
            "compliance_rate": 100.0
          },
          "audit_trails": {
            "completeness": 99.8,
            "integrity_verified": true,
            "retention_compliant": true
          },
          "data_integrity": {
            "tamper_evidence": 100.0,
            "change_controls": 98.5,
            "access_controls": 97.8
          }
        },
        "findings": [
          {
            "finding_id": "FDA_001",
            "requirement": "Electronic Signature Uniqueness",
            "status": "minor_gap",
            "description": "2 instances of shared signature credentials detected",
            "risk_level": "low",
            "remediation_plan": "User account cleanup scheduled for 2025-09-01",
            "due_date": "2025-09-01T23:59:59Z"
          }
        ]
      },
      {
        "framework": "ISO_27001",
        "compliance_score": 92.8,
        "status": "compliant",
        "requirements": {
          "total": 114,
          "compliant": 106,
          "partial": 7,
          "non_compliant": 1
        },
        "key_metrics": {
          "access_management": {
            "user_access_reviews": 98.2,
            "privileged_access_monitoring": 100.0,
            "access_certification": 94.5
          },
          "incident_management": {
            "response_time_compliance": 96.7,
            "documentation_completeness": 89.3,
            "escalation_procedures": 100.0
          }
        }
      }
    ],
    "risk_assessment": {
      "overall_risk": "low",
      "critical_risks": 0,
      "high_risks": 2,
      "medium_risks": 8,
      "low_risks": 15,
      "risk_trends": {
        "direction": "improving",
        "change_percent": -12.5
      }
    },
    "recent_violations": [
      {
        "violation_id": "viol_20250825_001",
        "framework": "GDPR",
        "severity": "medium",
        "description": "Data retention period exceeded for inactive user accounts",
        "detected_date": "2025-08-25T10:00:00Z",
        "resolution_status": "in_progress",
        "estimated_resolution": "2025-08-30T23:59:59Z"
      }
    ],
    "upcoming_requirements": [
      {
        "requirement": "Annual access certification",
        "framework": "SOX",
        "due_date": "2025-12-31T23:59:59Z",
        "preparation_status": "on_track",
        "completion_percent": 23
      }
    ]
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_compliance_abc123",
    "assessment_period": "2025-01-01 to 2025-08-26"
  }
}

Generate Audit Report

POST/v1/audit/reports

Generate comprehensive audit reports for compliance and regulatory purposes

Example Request

curl -X POST \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "compliance_summary",
    "framework": "FDA_21CFR11",
    "period": {
      "start": "2025-07-01T00:00:00Z",
      "end": "2025-08-26T23:59:59Z"
    },
    "scope": {
      "include_systems": ["production", "quality", "laboratory"],
      "include_users": "all",
      "include_violations": true,
      "include_remediation": true
    },
    "format": "pdf",
    "digital_signature": {
      "required": true,
      "signatory": "compliance_officer_001",
      "signature_meaning": "reviewed_and_approved"
    },
    "distribution": [
      "[email protected]",
      "[email protected]"
    ]
  }' \
  https://sapienstream.com/api/audit/reports

Example Response

{
  "success": true,
  "data": {
    "report_id": "report_compliance_20250826_001",
    "status": "generated",
    "report_type": "compliance_summary",
    "framework": "FDA_21CFR11",
    "period": {
      "start": "2025-07-01T00:00:00Z",
      "end": "2025-08-26T23:59:59Z",
      "duration_days": 57
    },
    "generation_info": {
      "generated_at": "2025-08-26T14:30:45.789Z",
      "generated_by": "user_compliance_001",
      "processing_time_ms": 15670,
      "data_sources": 8,
      "total_records_analyzed": 47839
    },
    "summary": {
      "overall_compliance_score": 96.2,
      "total_audit_entries": 47839,
      "compliance_violations": 3,
      "critical_findings": 0,
      "remediation_completed": 12,
      "pending_actions": 2
    },
    "digital_signature": {
      "signed": true,
      "signatory": "compliance_officer_001",
      "signature_timestamp": "2025-08-26T14:35:00.789Z",
      "signature_meaning": "reviewed_and_approved",
      "certificate_fingerprint": "SHA256:a1b2c3d4e5f6..."
    },
    "file_info": {
      "format": "pdf",
      "size_bytes": 2847392,
      "download_url": "https://sapienstream.com/api/audit/reports/report_compliance_20250826_001/download",
      "expires_at": "2025-09-26T14:30:45.789Z",
      "checksum": "sha256:def456abc789..."
    },
    "distribution": {
      "email_sent": true,
      "recipients": [
        "[email protected]",
        "[email protected]"
      ],
      "delivery_confirmation": true
    },
    "retention": {
      "retention_period": "10_years",
      "archive_location": "compliance_vault",
      "immutable": true
    }
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_generate_report_abc123"
  }
}

Forensic Investigations

POST/v1/audit/investigations

Create and manage forensic investigations for security incidents and compliance issues

Example Request

curl -X POST \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "investigation_type": "data_integrity_incident",
    "title": "Suspicious data modifications in production system",
    "priority": "high",
    "scope": {
      "time_range": {
        "start": "2025-08-25T00:00:00Z",
        "end": "2025-08-26T23:59:59Z"
      },
      "affected_systems": ["production_reactor_001", "quality_lab_system"],
      "potential_users": ["user_operator_003", "user_engineer_007"],
      "data_categories": ["process_parameters", "quality_results"]
    },
    "trigger_event": {
      "event_id": "audit_entry_20250826_001234",
      "description": "Unauthorized alarm limit changes detected"
    },
    "assigned_investigator": "investigator_security_001",
    "compliance_frameworks": ["FDA_21CFR11", "ISO_27001"],
    "automated_analysis": {
      "enable_pattern_detection": true,
      "enable_user_behavior_analysis": true,
      "enable_data_flow_mapping": true
    }
  }' \
  https://sapienstream.com/api/audit/investigations

Example Response

{
  "success": true,
  "data": {
    "investigation_id": "inv_20250826_data_integrity_001",
    "title": "Suspicious data modifications in production system",
    "status": "active",
    "priority": "high",
    "investigation_type": "data_integrity_incident",
    "created_at": "2025-08-26T14:30:45.789Z",
    "assigned_investigator": {
      "user_id": "investigator_security_001",
      "name": "Sarah Chen",
      "role": "Security Analyst",
      "certification": "CISSP, CISA"
    },
    "scope": {
      "time_range": {
        "start": "2025-08-25T00:00:00Z",
        "end": "2025-08-26T23:59:59Z",
        "duration_hours": 48
      },
      "affected_systems": ["production_reactor_001", "quality_lab_system"],
      "data_points_analyzed": 15847,
      "users_in_scope": 8
    },
    "preliminary_findings": {
      "suspicious_activities": 3,
      "policy_violations": 1,
      "unauthorized_changes": 2,
      "timeline_anomalies": 1
    },
    "evidence_collection": {
      "audit_entries_collected": 247,
      "system_logs_collected": 1543,
      "user_session_data": 12,
      "change_records": 89,
      "chain_of_custody_verified": true
    },
    "automated_analysis": {
      "pattern_detection": {
        "status": "completed",
        "patterns_found": 2,
        "confidence_score": 0.87
      },
      "user_behavior_analysis": {
        "status": "in_progress",
        "anomalies_detected": 1,
        "behavioral_baseline_deviation": 23.4
      },
      "data_flow_mapping": {
        "status": "queued",
        "estimated_completion": "2025-08-26T16:00:00Z"
      }
    },
    "compliance_implications": {
      "frameworks_affected": ["FDA_21CFR11", "ISO_27001"],
      "potential_violations": [
        {
          "framework": "FDA_21CFR11",
          "section": "11.10(e)",
          "description": "Inadequate access controls for electronic records",
          "severity": "medium"
        }
      ],
      "regulatory_notification_required": false
    },
    "next_steps": [
      "Interview affected users",
      "Analyze system access logs",
      "Review change management procedures",
      "Assess impact on product quality"
    ],
    "estimated_completion": "2025-08-30T17:00:00Z"
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_investigation_abc123",
    "case_number": "CASE-2025-08-001"
  }
}

Error Responses

Common Error Responses

Standard error codes and responses for the Audit API

403 Insufficient Privileges

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_AUDIT_PRIVILEGES",
    "message": "User does not have required audit access permissions",
    "details": {
      "required_permission": "audit:read:sensitive",
      "user_permissions": ["audit:read:basic"],
      "contact": "[email protected]"
    }
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_error_abc123"
  }
}

410 Data Archived

{
  "success": false,
  "error": {
    "code": "AUDIT_DATA_ARCHIVED",
    "message": "Requested audit data has been archived and requires special access",
    "details": {
      "archive_date": "2025-01-01T00:00:00Z",
      "archive_location": "long_term_compliance_storage",
      "retrieval_process": "Submit request through compliance portal",
      "estimated_retrieval_time": "24_hours"
    }
  },
  "metadata": {
    "timestamp": "2025-08-26T14:30:45.789Z",
    "request_id": "req_error_abc123"
  }
}

Next Steps

Explore related APIs and advanced audit capabilities

Authentication API

Manage user authentication and authorization

Compliance Framework

Learn about regulatory compliance features

Python SDK

Use the Python client for audit automation

Compliance Automation

Automate compliance monitoring and reporting