Compliance & Scanning API

v1.0StableLast updated: March 2026

Manage GDPR consent, data subject requests, HIPAA business associate agreements, compliance scanning rules, flagged traces, and audit logs. These endpoints support regulatory requirements across GDPR, HIPAA, and SOC 2.

Authentication

All compliance endpoints require authentication via session (dashboard) or API key (Authorization: Bearer header).

Authorization: Bearer thk_your_api_key

See Authentication for details on obtaining and managing API keys.

Some endpoints (BAA management, full compliance check details) require admin role. Non-admin users receive summary views.

Manage user consent for data processing purposes as required by GDPR Article 7.

List Consents

GET /api/v1/compliance/consents

Returns all consent records for the authenticated user.

Response:

{
  "consents": [
    {
      "id": "consent_abc123",
      "purpose": "analytics",
      "granted": true,
      "lawfulBasis": "consent",
      "grantedAt": "2026-01-15T10:00:00Z",
      "withdrawnAt": null
    }
  ]
}

POST /api/v1/compliance/consents/:purpose/grant

Grant consent for a specific processing purpose.

Path Parameters:

Parameter	Type	Description
`purpose`	string	One of: `essential`, `analytics`, `marketing`, `personalization`, `third_party`

Response:

{
  "success": true,
  "purpose": "analytics",
  "granted": true
}

POST /api/v1/compliance/consents/:purpose/withdraw

Withdraw previously granted consent. Cannot withdraw essential consent.

Response:

{
  "success": true,
  "purpose": "analytics",
  "withdrawn": true
}

Status	Description
400	Invalid purpose or attempting to withdraw `essential` consent
404	No active consent found for this purpose

Submit and track data subject requests as defined by GDPR Articles 15-22. All DSRs are automatically assigned a 30-day deadline per GDPR requirements.

List DSRs

GET /api/v1/compliance/dsr

Returns all data subject requests submitted by the authenticated user.

Response:

{
  "requests": [
    {
      "id": "dsr_abc123",
      "type": "access",
      "status": "pending",
      "createdAt": "2026-02-01T12:00:00Z",
      "dueDate": "2026-03-03T12:00:00Z",
      "completedAt": null,
      "downloadUrl": null
    }
  ]
}

Create DSR

POST /api/v1/compliance/dsr

Submit a new data subject request.

Request Body:

Field	Type	Required	Description
`requestType`	string	Yes	One of: `access`, `rectification`, `erasure`, `portability`, `restriction`, `objection`
`requestDetails`	string	No	Additional details about the request

Response (201):

{
  "id": "dsr_def456",
  "type": "erasure",
  "status": "pending",
  "dueDate": "2026-04-09T00:00:00Z"
}

Get DSR Status

GET /api/v1/compliance/dsr/:id

Get the current status of a specific DSR. Only the requester or an admin can view the details.

Response:

{
  "id": "dsr_def456",
  "type": "erasure",
  "status": "in_progress",
  "createdAt": "2026-03-10T12:00:00Z",
  "dueDate": "2026-04-09T12:00:00Z",
  "completedAt": null,
  "completionNotes": null
}

Export user data in machine-readable formats for data portability compliance.

Request Data Export

POST /api/v1/compliance/export/my-data

Generates a data export and returns a download link. Creates a DSR record automatically.

Request Body:

Field	Type	Default	Description
`format`	string	`"json"`	Export format: `json` or `csv`
`includeTraces`	boolean	`true`	Include trace data in export
`includeConsents`	boolean	`true`	Include consent records
`redactPII`	boolean	`false`	Redact PII from exported data
`traceLimit`	number	-	Max traces to export (1-100,000)

Response (201):

{
  "requestId": "dsr_exp789",
  "status": "completed",
  "downloadUrl": "/api/v1/compliance/export/download/dsr_exp789",
  "message": "Your data export is ready for download."
}

Download Export

GET /api/v1/compliance/export/download/:id

Download a completed data export. Returns the file as an attachment with the appropriate Content-Type (application/json or text/csv).

Request Erasure

POST /api/v1/compliance/erasure/request

Submit a right-to-be-forgotten request. Requires identity verification before processing.

Request Body:

Field	Type	Required	Description
`reason`	string	No	Reason for the erasure request

Response (201):

{
  "requestId": "erasure_abc123",
  "status": "awaiting_verification",
  "message": "Erasure request created. Identity verification required before processing."
}

Business Associate Agreements (HIPAA)

Manage BAAs for HIPAA compliance. All BAA endpoints require admin role.

List BAAs

GET /api/v1/compliance/baa

Response:

{
  "agreements": [
    {
      "id": "baa_abc123",
      "vendorName": "Cloud Provider Inc.",
      "status": "active",
      "agreementDate": "2025-06-01T00:00:00Z",
      "effectiveDate": "2025-07-01T00:00:00Z",
      "expirationDate": "2026-07-01T00:00:00Z",
      "vendorEmail": "legal@provider.com",
      "createdAt": "2025-06-01T09:00:00Z",
      "nextReviewDue": "2026-01-01T00:00:00Z"
    }
  ]
}

Create BAA

POST /api/v1/compliance/baa

Request Body:

Field	Type	Required	Description
`vendorName`	string	Yes	Name of the business associate
`vendorEmail`	string	No	Vendor contact email
`vendorContact`	string	No	Vendor contact name
`agreementDate`	string	Yes	Date agreement was signed (ISO 8601)
`effectiveDate`	string	Yes	Date agreement takes effect (ISO 8601)
`expirationDate`	string	No	Expiration date (ISO 8601). Review date auto-set to 6 months before.
`description`	string	No	Notes about the agreement

Response (201):

{
  "id": "baa_def456",
  "vendorName": "Cloud Provider Inc.",
  "status": "active",
  "agreementDate": "2025-06-01T00:00:00Z",
  "effectiveDate": "2025-07-01T00:00:00Z"
}

Update BAA

PUT /api/v1/compliance/baa/:id

Request Body:

Field	Type	Description
`status`	string	BAA status (e.g., `active`, `expired`, `terminated`)
`expirationDate`	string	Updated expiration date (ISO 8601)
`nextReviewDue`	string	Next review date (ISO 8601)
`notes`	string	Additional notes

Run Full Check

GET /api/v1/compliance/check

Runs automated compliance checks across GDPR, HIPAA, and SOC 2 frameworks. Admin users receive full issue details; non-admin users receive a summary.

Response (admin):

{
  "overallStatus": "warning",
  "score": 82,
  "timestamp": "2026-03-10T15:30:00Z",
  "issues": [
    {
      "framework": "gdpr",
      "severity": "high",
      "check": "consent_coverage",
      "message": "3 users missing analytics consent records",
      "recommendation": "Review consent collection flow"
    }
  ],
  "checks": {
    "gdpr": {
      "status": "warning",
      "score": 75,
      "issueCount": 2,
      "criticalIssues": 0,
      "checks": [...]
    },
    "hipaa": {
      "status": "pass",
      "score": 95,
      "issueCount": 0,
      "criticalIssues": 0,
      "checks": [...]
    },
    "soc2": {
      "status": "pass",
      "score": 90,
      "issueCount": 1,
      "criticalIssues": 0,
      "checks": [...]
    }
  }
}

Response (non-admin): Same structure but with an empty issues array and a message field: "Contact your administrator for detailed issue information."

Get Summary

GET /api/v1/compliance/check/summary

Returns a simplified compliance summary accessible to all authenticated users.

Response:

{
  "status": "warning",
  "score": 82,
  "gdpr": { "status": "warning", "score": 75, "issueCount": 2 },
  "hipaa": { "status": "pass", "score": 95, "issueCount": 0 },
  "soc2": { "status": "pass", "score": 90, "issueCount": 1 },
  "lastChecked": "2026-03-10T15:30:00Z"
}

Risk Assessment (SOC 2)

Get Risk Assessment

GET /api/v1/compliance/risk

Returns the current risk assessment for the company, including risk level and overall score.

Get Risk History

GET /api/v1/compliance/risk/history

Query Parameters:

Parameter	Type	Default	Description
`limit`	number	10	Number of historical assessments to return

Response:

{
  "assessments": [
    {
      "riskLevel": "low",
      "overallScore": 88,
      "timestamp": "2026-03-10T12:00:00Z"
    }
  ]
}

SLA Monitoring (SOC 2)

Get SLA Report

GET /api/v1/compliance/sla

Query Parameters:

Parameter	Type	Default	Description
`days`	number	30	Time period in days

Get System Health

GET /api/v1/compliance/sla/health

Returns component-level health status.

Response:

{
  "timestamp": "2026-03-10T15:00:00Z",
  "components": [
    { "name": "database", "status": "healthy", "latencyMs": 5 },
    { "name": "redis", "status": "healthy", "latencyMs": 2 }
  ],
  "healthy": true
}

Audit Logs

List Audit Logs

GET /api/v1/compliance/audit-logs

Paginated list of audit log entries for the company.

Query Parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	50	Items per page (max 100)
`action`	string	-	Filter by action type
`outcome`	string	-	Filter by outcome
`startDate`	string	-	Start date (ISO 8601)
`endDate`	string	-	End date (ISO 8601)

Response:

{
  "logs": [
    {
      "id": "log_abc123",
      "userId": "user_xyz",
      "action": "trace.delete",
      "resourceType": "trace",
      "resourceId": "tr_abc",
      "severity": "warning",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "details": { "reason": "GDPR erasure request" },
      "timestamp": "2026-03-10T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 230,
    "totalPages": 5
  }
}

Export Audit Logs (CSV)

GET /api/v1/compliance/audit-logs/export

Downloads audit logs as a CSV file. Useful for SOC 2 audit evidence collection.

Query Parameters:

Parameter	Type	Default	Description
`days`	number	30	Number of days of logs to export

Response: CSV file download with headers: Timestamp, User ID, Action, Resource Type, Resource ID, Severity, IP Address.

CSV exports include formula injection protection. Fields starting with =, +, -, or @ are prefixed with a single quote to prevent spreadsheet formula execution.

Compliance Scanning Rules

Define rules that automatically scan traces for PII and compliance violations. The scanning pipeline runs asynchronously via a background job queue.

All scanning endpoints are mounted at /api/v1/compliance/scanning.

List Scan Rules

GET /api/v1/compliance/scanning/rules

Returns all compliance scan rules for the company.

Response:

{
  "rules": [
    {
      "id": "rule_abc123",
      "name": "PII in Agent Responses",
      "description": "Detect email and SSN in agent output fields",
      "isEnabled": true,
      "piiTypes": ["email", "ssn", "credit_card"],
      "fieldsToScan": ["output", "agentResponse"],
      "minConfidence": "high",
      "autoFlag": true,
      "autoAlert": false,
      "alertSeverity": "warning",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

Create Scan Rule

POST /api/v1/compliance/scanning/rules

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Rule name (1-200 characters)
`description`	string	No	Human-readable description
`isEnabled`	boolean	No	Whether the rule is active (default: depends on creation method)
`piiTypes`	string[]	Yes	PII types to detect (e.g., `email`, `ssn`, `phone`, `credit_card`)
`fieldsToScan`	string[]	No	Trace fields to scan (e.g., `input`, `output`, `agentResponse`)
`minConfidence`	string	No	Minimum confidence threshold (e.g., `low`, `medium`, `high`)
`autoFlag`	boolean	No	Automatically flag traces with violations
`autoAlert`	boolean	No	Send alerts on violation detection
`alertSeverity`	string	No	Alert severity: `info`, `warning`, `error`, `critical`

Response (201):

{
  "rule": {
    "id": "rule_new123",
    "name": "PII in Agent Responses",
    "isEnabled": true,
    "piiTypes": ["email", "ssn"],
    "autoFlag": true,
    "createdAt": "2026-03-10T12:00:00Z"
  }
}

Update Scan Rule

PUT /api/v1/compliance/scanning/rules/:id

All fields from the create schema are accepted and optional.

Response:

{
  "rule": { ... }
}

Delete Scan Rule

DELETE /api/v1/compliance/scanning/rules/:id

Response:

{
  "success": true
}

Seed Default Rules

POST /api/v1/compliance/scanning/rules/seed

Creates a set of pre-configured scan rules (all disabled by default). Useful for onboarding.

Response:

{
  "rules": [
    { "id": "rule_1", "name": "Email Detection", "isEnabled": false, ... },
    { "id": "rule_2", "name": "SSN Detection", "isEnabled": false, ... }
  ]
}

Compliance Violations

Violations are created when the scanning pipeline detects PII or policy violations in traces.

List Violations

GET /api/v1/compliance/scanning/violations

Query Parameters:

Parameter	Type	Default	Description
`status`	string	-	Filter: `open`, `acknowledged`, `resolved`, `false_positive`
`ruleId`	string	-	Filter by scan rule ID
`agentId`	string	-	Filter by agent ID
`piiType`	string	-	Filter by PII type
`startDate`	string	-	Start date (ISO 8601)
`endDate`	string	-	End date (ISO 8601)
`limit`	number	50	Items per page (1-100)
`offset`	number	0	Pagination offset

Response:

{
  "violations": [
    {
      "id": "viol_abc123",
      "ruleId": "rule_abc123",
      "ruleName": "PII in Agent Responses",
      "traceId": "tr_xyz789",
      "agentId": "agent_abc",
      "piiType": "email",
      "status": "open",
      "detectedAt": "2026-03-10T14:30:00Z"
    }
  ],
  "total": 42
}

Get Violation Detail

GET /api/v1/compliance/scanning/violations/:id

Get Violations by Trace

GET /api/v1/compliance/scanning/violations/by-trace/:traceId

Returns all violations found for a specific trace.

Violation Statistics

GET /api/v1/compliance/scanning/violations/stats

Query Parameters:

Parameter	Type	Description
`agentId`	string	Optional agent filter

Response:

{
  "stats": {
    "total": 150,
    "byStatus": {
      "open": 42,
      "acknowledged": 30,
      "resolved": 70,
      "false_positive": 8
    },
    "byPiiType": {
      "email": 60,
      "phone": 40,
      "ssn": 30,
      "credit_card": 20
    }
  }
}

Update Violation Status

PUT /api/v1/compliance/scanning/violations/:id

Request Body:

Field	Type	Required	Description
`status`	string	Yes	New status: `open`, `acknowledged`, `resolved`, `false_positive`
`notes`	string	No	Resolution or review notes

Bulk Update Violations

POST /api/v1/compliance/scanning/violations/bulk

Request Body:

Field	Type	Required	Description
`ids`	string[]	Yes	Violation IDs to update (max 100)
`status`	string	Yes	New status: `open`, `acknowledged`, `resolved`, `false_positive`

Response:

{
  "updated": 15
}

Backfill Scan

POST /api/v1/compliance/scanning/backfill

Enqueue compliance scans for existing traces. Requires at least one enabled scan rule.

Query Parameters:

Parameter	Type	Default	Description
`limit`	number	200	Max traces to scan (up to 500)

Response:

{
  "total": 200,
  "enqueued": 198
}

Scanning Health

GET /api/v1/compliance/scanning/health

Returns the health status of the compliance scanning pipeline.

Response:

{
  "active": true,
  "redis": true,
  "workerInitialized": true,
  "complianceQueue": { "waiting": 5, "active": 2, "completed": 1500, "failed": 3 }
}

Flagged Traces

Flag traces for human review when issues are detected — whether by automated compliance scanning, guardrail violations, or manual observation.

All flagged trace endpoints are mounted at /api/flagged-traces.

List Flagged Traces

GET /api/flagged-traces

Returns flagged traces with filtering, pagination, and aggregate statistics.

Query Parameters:

Parameter	Type	Default	Description
`status`	string	-	Filter: `open`, `in_review`, `resolved`
`reason`	string	-	Filter: `hallucination`, `poor_quality`, `compliance_concern`, `unexpected_behavior`, `customer_complaint`, `other`
`assignedTo`	string	-	Filter by assigned user ID
`agentId`	string	-	Filter by agent ID
`limit`	number	20	Items per page (1-100)
`offset`	number	0	Pagination offset
`sort`	string	`"newest"`	Sort order: `newest` or `oldest`

Response:

{
  "data": [
    {
      "id": "flag_abc123",
      "traceId": "tr_xyz789",
      "agentId": "agent_abc",
      "reason": "compliance_concern",
      "status": "open",
      "notes": "PII detected in agent response",
      "flaggedBy": "user_123",
      "assignedTo": "user_456",
      "createdAt": "2026-03-10T14:00:00Z"
    }
  ],
  "total": 25,
  "stats": {
    "open": 10,
    "in_review": 8,
    "resolved": 7
  },
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Flag a Trace

POST /api/flagged-traces

Request Body:

Field	Type	Required	Description
`traceId`	string	Yes	ID of the trace to flag
`agentId`	string	Yes	ID of the agent that produced the trace
`reason`	string	Yes	Flag reason: `hallucination`, `poor_quality`, `compliance_concern`, `unexpected_behavior`, `customer_complaint`, `other`
`assignedTo`	string	No	User ID to assign for review (must belong to your team)
`notes`	string	No	Additional context (max 2,000 characters)

⚠️

A trace can only have one active flag (status open or in_review). Attempting to flag an already-flagged trace returns a 409 Conflict with the existing flag ID.

Response (201):

{
  "id": "flag_new123",
  "traceId": "tr_xyz789",
  "agentId": "agent_abc",
  "reason": "compliance_concern",
  "status": "open",
  "flaggedBy": "user_123",
  "assignedTo": "user_456",
  "createdAt": "2026-03-10T15:00:00Z"
}

Get Flag Detail

GET /api/flagged-traces/:flagId

Returns the full flag record including review history.

Check if Trace is Flagged

GET /api/flagged-traces/by-trace/:traceId

Returns the active flag for a trace, or 404 if the trace is not flagged.

Update Flag

PATCH /api/flagged-traces/:flagId

Update the status or assignment of a flagged trace.

Request Body:

Field	Type	Description
`status`	string	New status: `open`, `in_review`, `resolved`
`assignedTo`	string \| null	Reassign or unassign a reviewer
`resolutionNotes`	string	Resolution details (max 5,000 characters)

Delete Flag

DELETE /api/flagged-traces/:flagId

Remove a flag. Only the user who created the flag can delete it.

Status	Description
200	Flag deleted successfully
403	You are not authorized to delete this flag
404	Flag not found

Add Comment

POST /api/flagged-traces/:flagId/comments

Add a comment to a flagged trace for collaborative review.

Request Body:

Field	Type	Required	Description
`content`	string	Yes	Comment text (1-5,000 characters)

Response (201):

{
  "id": "comment_abc123",
  "flagId": "flag_abc123",
  "userId": "user_123",
  "content": "Confirmed PII leak in the response. Needs guardrail update.",
  "createdAt": "2026-03-10T15:30:00Z"
}

ThinkHive provides comprehensive GDPR support through the endpoints above:

GDPR Article	Feature	Endpoint
Article 7	Consent management	`GET/POST /compliance/consents`
Article 15	Right of access	`POST /compliance/dsr` (type: `access`)
Article 16	Right to rectification	`POST /compliance/dsr` (type: `rectification`)
Article 17	Right to erasure	`POST /compliance/erasure/request`
Article 18	Right to restriction	`POST /compliance/dsr` (type: `restriction`)
Article 20	Data portability	`POST /compliance/export/my-data`
Article 21	Right to object	`POST /compliance/dsr` (type: `objection`)

All DSRs are automatically assigned a 30-day completion deadline per GDPR requirements. ThinkHive tracks status and due dates to help you stay compliant.

HIPAA Considerations

For organizations handling protected health information (PHI):

BAA Management — Track business associate agreements through the /compliance/baa endpoints with automatic review date scheduling (6 months before expiration).
PII Redaction — Use the Guardrails API PII scanner with HIPAA-specific entity types (medical_record_number, health_plan_id, npi) to redact PHI before storage.
Audit Logging — Every data access, modification, and deletion is recorded in the audit log, exportable as CSV for compliance evidence.
Compliance Scanning — Configure scan rules targeting PHI-specific PII types to automatically detect violations in trace data.

⚠️

ThinkHive can sign a BAA for enterprise customers. Contact sales@thinkhive.ai to execute a BAA before processing any PHI.

SOC 2 Audit Support

ThinkHive includes built-in SOC 2 readiness through:

Automated Compliance Checks — The /compliance/check endpoint validates controls across all three frameworks and produces a scored report.
Risk Assessment — The /compliance/risk endpoint provides current risk posture with historical trending via /compliance/risk/history.
SLA Monitoring — The /compliance/sla endpoint generates availability and performance reports. The /compliance/sla/health endpoint provides real-time component status.
Audit Log Export — CSV export of all audit events via /compliance/audit-logs/export for evidence collection during SOC 2 audits.

Guardrails Integration

Flagged traces connect directly to the Guardrails system:

Automated Flagging — When a compliance scan rule has autoFlag: true, traces with violations are automatically flagged with reason compliance_concern.
Guardrail-to-Flag Pipeline — When a guardrail scan returns block or flag actions, the trace can be flagged for human review.
Review Workflow — Team members can review flagged traces, add comments, update guardrail policies based on findings, and resolve flags.
Violation Correlation — Use GET /compliance/scanning/violations/by-trace/:traceId alongside GET /flagged-traces/by-trace/:traceId to see both automated detections and human flags for the same trace.

Rate Limits

Endpoint Group	Rate Limit
Flagged traces (create)	30 per 15 minutes
Flagged trace comments	60 per 15 minutes
Compliance scanning	Standard API rate limits
Data export	10 per hour

Error Codes

Status	Code	Description
400	`BAD_REQUEST`	Invalid request body or parameters
401	`UNAUTHORIZED`	Missing or invalid authentication
403	`FORBIDDEN`	Insufficient permissions (e.g., non-admin accessing BAA endpoints)
404	`NOT_FOUND`	Resource not found or not accessible
409	`CONFLICT`	Trace already flagged
429	`RATE_LIMIT_EXCEEDED`	Too many requests
503	`SERVICE_UNAVAILABLE`	Database or scanning pipeline unavailable

Next Steps

Guardrails API — Real-time PII scanning and content filtering
Traces API — Trace ingestion and querying
Authentication — API key management
Compliance Guide — Step-by-step setup for PII redaction and compliance

Webhooks & Notifications

Compliance & Scanning API

Authentication

Consent Management (GDPR)

List Consents

Grant Consent

Withdraw Consent

Data Subject Requests (GDPR)

List DSRs

Create DSR

Get DSR Status

Data Export (GDPR Article 20)

Request Data Export

Download Export

Data Erasure (GDPR Article 17)

Request Erasure

Business Associate Agreements (HIPAA)

List BAAs

Create BAA

Update BAA

Compliance Check (GDPR / HIPAA / SOC 2)

Run Full Check

Get Summary

Risk Assessment (SOC 2)

Get Risk Assessment

Get Risk History

SLA Monitoring (SOC 2)

Get SLA Report

Get System Health

Audit Logs

List Audit Logs

Export Audit Logs (CSV)

Compliance Scanning Rules

List Scan Rules

Create Scan Rule

Update Scan Rule

Delete Scan Rule

Seed Default Rules

Compliance Violations

List Violations

Get Violation Detail

Get Violations by Trace

Violation Statistics

Update Violation Status

Bulk Update Violations

Backfill Scan

Scanning Health

Flagged Traces

List Flagged Traces

Flag a Trace

Get Flag Detail

Check if Trace is Flagged

Update Flag

Delete Flag

Add Comment

GDPR Compliance Features

HIPAA Considerations

SOC 2 Audit Support

Guardrails Integration

Rate Limits

Error Codes

Next Steps