Integration API Reference

This document provides comprehensive API reference for integrating with Supernal Coding's compliance platform. The API follows REST principles and provides both synchronous and asynchronous operations for compliance management.

Base URL and Authentication

Base URL

https://api.supernal-coding.com/v1

Authentication

All API requests require authentication using API keys:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.supernal-coding.com/v1/requirements

API Key Management

// Generate API key
POST /auth/api-keys
{
  "name": "integration-key",
  "permissions": ["read:requirements", "write:requirements"],
  "expiresIn": "1y"
}

// Response
{
  "id": "ak_1234567890",
  "key": "sk_live_1234567890abcdef",
  "name": "integration-key",
  "permissions": ["read:requirements", "write:requirements"],
  "expiresAt": "2024-11-03T00:00:00Z"
}

Core API Endpoints

Requirements Management

List Requirements

GET /requirements

Parameters:

framework (string, optional): Filter by compliance framework
status (string, optional): Filter by requirement status
limit (integer, optional): Number of results to return (default: 50)
offset (integer, optional): Pagination offset

Response:

{
  "data": [
    {
      "id": "req-001",
      "title": "User Authentication",
      "description": "Implement secure user authentication",
      "framework": "iso13485",
      "status": "pending",
      "priority": "high",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Create Requirement

POST /requirements

Request Body:

{
  "title": "Data Encryption",
  "description": "Implement encryption for sensitive data",
  "framework": "gdpr",
  "category": "security",
  "priority": "high",
  "acceptanceCriteria": [
    "Data must be encrypted at rest",
    "Data must be encrypted in transit"
  ]
}

Response:

{
  "id": "req-002",
  "title": "Data Encryption",
  "description": "Implement encryption for sensitive data",
  "framework": "gdpr",
  "category": "security",
  "priority": "high",
  "status": "pending",
  "acceptanceCriteria": [
    "Data must be encrypted at rest",
    "Data must be encrypted in transit"
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Get Requirement Details

GET /requirements/{id}

Response:

{
  "id": "req-001",
  "title": "User Authentication",
  "description": "Implement secure user authentication",
  "framework": "iso13485",
  "category": "access-control",
  "priority": "high",
  "status": "in-progress",
  "acceptanceCriteria": [
    "Users must authenticate with username/password",
    "Multi-factor authentication must be supported",
    "Session timeout must be configurable"
  ],
  "technicalContext": {
    "scope": "Authentication system",
    "dataFlow": "User credentials → Authentication service → Session management",
    "relatedComponents": ["auth-service", "session-manager"]
  },
  "implementation": {
    "testFile": "tests/auth.test.js",
    "gitBranch": "feature/user-auth",
    "relatedIssues": ["#123", "#124"]
  },
  "validation": {
    "status": "passed",
    "lastValidated": "2024-01-01T00:00:00Z",
    "issues": []
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Update Requirement

PUT /requirements/{id}

Request Body:

{
  "status": "completed",
  "implementation": {
    "testFile": "tests/auth.test.js",
    "gitBranch": "feature/user-auth",
    "completedAt": "2024-01-01T00:00:00Z"
  }
}

Validate Requirement

POST /requirements/{id}/validate

Response:

{
  "valid": true,
  "score": 95,
  "issues": [],
  "suggestions": [
    "Consider adding password complexity requirements",
    "Add rate limiting for authentication attempts"
  ],
  "complianceMapping": {
    "iso13485": ["4.1.5", "4.2.3"],
    "gdpr": ["Article 32"]
  }
}

Compliance Management

Get Compliance Status

GET /compliance/status

Parameters:

framework (string, optional): Specific framework to check

Response:

{
  "overallScore": 87,
  "frameworks": {
    "iso13485": {
      "score": 92,
      "status": "compliant",
      "requirements": {
        "total": 50,
        "completed": 46,
        "inProgress": 3,
        "pending": 1
      },
      "lastAssessment": "2024-01-01T00:00:00Z"
    },
    "gdpr": {
      "score": 82,
      "status": "mostly-compliant",
      "requirements": {
        "total": 30,
        "completed": 25,
        "inProgress": 4,
        "pending": 1
      },
      "lastAssessment": "2024-01-01T00:00:00Z"
    }
  }
}

Generate Compliance Report

POST /compliance/reports

Request Body:

{
  "framework": "iso13485",
  "format": "pdf",
  "includeEvidence": true,
  "dateRange": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-12-31T23:59:59Z"
  }
}

Response:

{
  "reportId": "rpt-001",
  "status": "generating",
  "estimatedCompletion": "2024-01-01T00:05:00Z",
  "downloadUrl": null
}

Get Report Status

GET /compliance/reports/{reportId}

Response:

{
  "reportId": "rpt-001",
  "status": "completed",
  "downloadUrl": "https://api.supernal-coding.com/v1/compliance/reports/rpt-001/download",
  "generatedAt": "2024-01-01T00:04:32Z",
  "expiresAt": "2024-01-08T00:04:32Z"
}

Audit Management

List Audit Findings

GET /audits/findings

Parameters:

framework (string, optional): Filter by framework
severity (string, optional): Filter by severity (low, medium, high, critical)
status (string, optional): Filter by status (open, in-progress, resolved)

Response:

{
  "data": [
    {
      "id": "finding-001",
      "title": "Missing audit trail for user deletions",
      "description": "User deletion operations are not being logged",
      "framework": "fda21cfr11",
      "severity": "high",
      "status": "open",
      "requirementId": "req-fda-010",
      "discoveredAt": "2024-01-01T00:00:00Z",
      "dueDate": "2024-01-15T00:00:00Z"
    }
  ]
}

Create Audit Finding

POST /audits/findings

Request Body:

{
  "title": "Incomplete access control documentation",
  "description": "Access control procedures are not fully documented",
  "framework": "soc2",
  "severity": "medium",
  "requirementId": "req-soc-001",
  "evidence": [
    "Screenshot of missing documentation",
    "Interview notes with security team"
  ]
}

Update Finding Status

PATCH /audits/findings/{id}

Request Body:

{
  "status": "resolved",
  "resolution": "Access control procedures have been documented and approved",
  "resolvedAt": "2024-01-01T00:00:00Z",
  "evidence": ["Updated documentation", "Approval email"]
}

Framework Management

List Supported Frameworks

GET /frameworks

Response:

{
  "data": [
    {
      "id": "iso13485",
      "name": "ISO 13485",
      "description": "Medical Device Quality Management",
      "version": "2016",
      "categories": ["quality", "medical-device"],
      "requirementCount": 50,
      "supported": true
    },
    {
      "id": "gdpr",
      "name": "GDPR",
      "description": "General Data Protection Regulation",
      "version": "2018",
      "categories": ["privacy", "data-protection"],
      "requirementCount": 30,
      "supported": true
    }
  ]
}

Get Framework Details

GET /frameworks/{id}

Response:

{
  "id": "iso13485",
  "name": "ISO 13485",
  "description": "Medical Device Quality Management System",
  "version": "2016",
  "categories": ["quality", "medical-device"],
  "requirements": [
    {
      "id": "req-iso-001",
      "section": "4.1",
      "title": "Quality Management System",
      "description": "General requirements for QMS"
    }
  ],
  "validationRules": [
    {
      "id": "rule-001",
      "name": "Document Control",
      "description": "All documents must be controlled"
    }
  ]
}

Batch Operations

Bulk Requirement Creation

POST /requirements/batch

Request Body:

{
  "requirements": [
    {
      "title": "Data Backup",
      "framework": "iso13485",
      "priority": "high"
    },
    {
      "title": "Access Logging",
      "framework": "soc2",
      "priority": "medium"
    }
  ]
}

Response:

{
  "created": [
    {
      "id": "req-003",
      "title": "Data Backup",
      "status": "created"
    },
    {
      "id": "req-004",
      "title": "Access Logging",
      "status": "created"
    }
  ],
  "errors": []
}

Bulk Status Updates

PATCH /requirements/batch

Request Body:

{
  "updates": [
    {
      "id": "req-001",
      "status": "completed"
    },
    {
      "id": "req-002",
      "status": "in-progress"
    }
  ]
}

Error Handling

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ],
    "requestId": "req_1234567890"
  }
}

Common Error Codes

AUTHENTICATION_ERROR (401): Invalid or missing API key
AUTHORIZATION_ERROR (403): Insufficient permissions
VALIDATION_ERROR (400): Request validation failed
NOT_FOUND (404): Resource not found
RATE_LIMIT_EXCEEDED (429): Too many requests
INTERNAL_ERROR (500): Server error

Rate Limiting

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 60

SDK Examples

Node.js SDK

import { SupernalCoding } from '@supernal-coding/node-sdk';

const client = new SupernalCoding({
  apiKey: 'your-api-key',
  baseURL: 'https://api.supernal-coding.com/v1',
});

// Create requirement
const requirement = await client.requirements.create({
  title: 'User Authentication',
  framework: 'iso13485',
  priority: 'high',
});

// Get compliance status
const status = await client.compliance.getStatus();

// Subscribe to real-time events
client.on('requirement.updated', (event) => {
  console.log('Requirement updated:', event);
});

Python SDK

from supernal_coding import SupernalCoding

client = SupernalCoding(api_key='your-api-key')

# Create requirement
requirement = client.requirements.create(
    title='Data Encryption',
    framework='gdpr',
    priority='high'
)

# Get compliance status
status = client.compliance.get_status()

# Generate report
report = client.compliance.generate_report(
    framework='gdpr',
    format='pdf'
)

Integration Patterns

Webhook Integration

// Express.js webhook handler
app.post('/webhooks/supernal', (req, res) => {
  const event = req.body;

  // Verify webhook signature
  const signature = req.headers['x-supernal-signature'];
  if (!verifySignature(signature, req.body)) {
    return res.status(401).send('Invalid signature');
  }

  // Handle event
  switch (event.type) {
    case 'requirement.updated':
      handleRequirementUpdate(event.data);
      break;
    case 'compliance.score_changed':
      handleComplianceChange(event.data);
      break;
  }

  res.status(200).send('OK');
});

CI/CD Integration

# GitHub Actions example
- name: Validate Compliance
  uses: supernal-coding/github-action@v1
  with:
    api-key: ${{ secrets.SUPERNAL_API_KEY }}
    framework: iso13485
    fail-on-score: 80

Claude Code Integration - AI-powered development integration
Integration Examples - Practical integration examples
WebSocket Integration - Real-time integration
Integration Architecture - System architecture

This API reference provides comprehensive integration capabilities for building compliance-driven applications with Supernal Coding's platform.

Base URL and Authentication​

Base URL​

Authentication​

API Key Management​

Core API Endpoints​

Requirements Management​

List Requirements​

Create Requirement​

Get Requirement Details​

Update Requirement​

Validate Requirement​

Compliance Management​

Get Compliance Status​

Generate Compliance Report​

Get Report Status​

Audit Management​

List Audit Findings​

Create Audit Finding​

Update Finding Status​

Framework Management​

List Supported Frameworks​

Get Framework Details​

Batch Operations​

Bulk Requirement Creation​

Bulk Status Updates​

Error Handling​

Error Response Format​

Common Error Codes​

Rate Limiting​

SDK Examples​

Node.js SDK​

Python SDK​

Integration Patterns​

Webhook Integration​

CI/CD Integration​

Related Documentation​

Base URL and Authentication

Base URL

Authentication

API Key Management

Core API Endpoints

Requirements Management

List Requirements

Create Requirement

Get Requirement Details

Update Requirement

Validate Requirement

Compliance Management

Get Compliance Status

Generate Compliance Report

Get Report Status

Audit Management

List Audit Findings

Create Audit Finding

Update Finding Status

Framework Management

List Supported Frameworks

Get Framework Details

Batch Operations

Bulk Requirement Creation

Bulk Status Updates

Error Handling

Error Response Format

Common Error Codes

Rate Limiting

SDK Examples

Node.js SDK

Python SDK

Integration Patterns

Webhook Integration

CI/CD Integration

Related Documentation