API Integration
Complete API reference for programmatic verification access
API Overview
The AI Verification Service provides a RESTful API for programmatic access to verification functionality. This allows custom integrations, automated workflows, and advanced use cases beyond the Dashboard interface.
Base URL: https://ai.copyrightchains.com/api/v1
Authentication: Session-based (SempreID cookies)
Response Format: JSON
Rate Limiting: 100 requests per hour per user
Authentication
All API endpoints require valid SempreID authentication via session cookies. Administrator status is verified automatically on each request.
Session-Based Authentication
The API uses the same authentication system as the Dashboard. When your browser has an active SempreID session, API calls automatically include authentication credentials.
- No API Keys Required: Session cookies provide authentication
- Automatic Admin Validation: Every request checks administrator status
- Session Expiry: Sessions expire after 24 hours of inactivity
- Secure Cookies: HttpOnly, Secure, SameSite protection
Making Authenticated Requests
// JavaScript fetch example
fetch('https://ai.copyrightchains.com/api/v1/verify', {
method: 'POST',
credentials: 'include', // Important: includes cookies
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ ... })
})
.then(response => response.json())
.then(data => console.log(data));
API Endpoints
POST /api/v1/verify
Submit a new verification request
Authentication: Required (Admin only)
Request Body:
{
"registrationId": "550e8400-e29b-41d4-a716-446655440000",
"type": "musical_work",
"content": {
"title": "My Song Title",
"files": {
"audio": "base64-encoded-audio-data",
"lyrics": "base64-encoded-lyrics-pdf",
"score": "base64-encoded-score-pdf"
},
"metadata": {
"duration": 180,
"format": "mp3",
"bitrate": 320,
"sampleRate": 44100
}
}
}
Response (200 OK):
{
"success": true,
"verificationId": "660e8400-e29b-41d4-a716-446655440001",
"status": "queued",
"estimatedTime": 60,
"queuePosition": 3
}
Error Responses:
// 401 Unauthorized
{
"success": false,
"error": "Authentication required",
"code": "AUTH_REQUIRED"
}
// 403 Forbidden
{
"success": false,
"error": "Administrator access required",
"code": "INSUFFICIENT_PERMISSIONS"
}
// 400 Bad Request
{
"success": false,
"error": "Invalid request format",
"code": "INVALID_REQUEST",
"details": ["registrationId is required"]
}
GET /api/v1/status/:verificationId
Check verification status
Authentication: Required
Path Parameters:
- verificationId: UUID of verification to check
Response (200 OK):
{
"verificationId": "660e8400-e29b-41d4-a716-446655440001",
"status": "processing",
"progress": 65,
"currentStep": "Analyzing audio fingerprints",
"created_at": "2025-10-16T12:00:00Z",
"updated_at": "2025-10-16T12:00:45Z",
"estimatedCompletion": "2025-10-16T12:01:30Z"
}
Status Values:
- queued: Waiting to be processed
- processing: Currently being analyzed
- completed: Analysis finished, report available
- failed: Error occurred during processing
GET /api/v1/report/:verificationId
Retrieve verification report
Authentication: Required
Path Parameters:
- verificationId: UUID of completed verification
Response (200 OK):
{
"verificationId": "660e8400-e29b-41d4-a716-446655440001",
"registrationId": "550e8400-e29b-41d4-a716-446655440000",
"type": "musical_work",
"status": "completed",
"report": {
"overallRisk": 15,
"infringementRisk": 10,
"launderingRisk": 5,
"authenticityScore": 95,
"duplicateProbability": 0,
"recommendation": "approve",
"summary": "No significant concerns detected...",
"findings": {
"infringement": {
"matches": [],
"confidence": "low"
},
"laundering": {
"indicators": [],
"confidence": "low"
},
"authenticity": {
"aiProbability": 5,
"confidence": "high"
},
"duplicates": {
"matches": [],
"confidence": "low"
}
},
"providerResults": [
{
"provider": "openai",
"model": "gpt-4o",
"analysis": "...",
"confidence": 92
},
{
"provider": "anthropic",
"model": "claude-3-sonnet",
"analysis": "...",
"confidence": 89
}
]
},
"processingTime": 45,
"created_at": "2025-10-16T12:00:00Z",
"completed_at": "2025-10-16T12:00:45Z"
}
Error (404 Not Found):
{
"success": false,
"error": "Verification not found",
"code": "NOT_FOUND"
}
GET /api/v1/health
Check service health
Authentication: Not required (public endpoint)
Response (200 OK):
{
"status": "healthy",
"uptime": 86400,
"version": "1.0.0",
"providers": {
"openai": "operational",
"anthropic": "operational",
"google": "operational",
"custom_ml": "operational"
},
"queue": {
"waiting": 5,
"active": 2,
"completed": 1234,
"failed": 12
},
"database": "connected",
"redis": "connected"
}
GET /api/v1/metrics
Retrieve service metrics
Authentication: Required (Admin only)
Response (200 OK):
{
"totalVerifications": 1246,
"todayVerifications": 47,
"averageProcessingTime": 42,
"successRate": 98.5,
"providerStats": {
"openai": {
"calls": 1246,
"failures": 8,
"avgLatency": 1200
},
"anthropic": {
"calls": 1246,
"failures": 5,
"avgLatency": 1800
}
},
"queueStats": {
"avgWaitTime": 15,
"maxWaitTime": 120,
"currentBacklog": 7
}
}
Code Examples
JavaScript Example
async function verifyRegistration(registrationId, content) {
try {
// Submit verification
const submitResponse = await fetch(
'https://ai.copyrightchains.com/api/v1/verify',
{
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
registrationId,
type: 'musical_work',
content
})
}
);
const { verificationId } = await submitResponse.json();
// Poll for completion
let status = 'queued';
while (status === 'queued' || status === 'processing') {
await new Promise(resolve => setTimeout(resolve, 5000));
const statusResponse = await fetch(
`https://ai.copyrightchains.com/api/v1/status/${verificationId}`,
{ credentials: 'include' }
);
const statusData = await statusResponse.json();
status = statusData.status;
console.log(`Progress: ${statusData.progress}%`);
}
// Retrieve report
const reportResponse = await fetch(
`https://ai.copyrightchains.com/api/v1/report/${verificationId}`,
{ credentials: 'include' }
);
const report = await reportResponse.json();
return report;
} catch (error) {
console.error('Verification failed:', error);
throw error;
}
}
// Usage
const content = {
title: "My Song",
files: {
audio: "base64-encoded-audio",
lyrics: "base64-encoded-lyrics"
},
metadata: {
duration: 180,
format: "mp3",
bitrate: 320
}
};
verifyRegistration('registration-uuid', content)
.then(report => {
console.log('Overall Risk:', report.report.overallRisk);
console.log('Recommendation:', report.report.recommendation);
});
Python Example
import requests
import time
import base64
class AIVerificationClient:
def __init__(self, base_url, session_cookie):
self.base_url = base_url
self.session = requests.Session()
self.session.cookies.set('sempreid_session', session_cookie)
def submit_verification(self, registration_id, content):
"""Submit verification request"""
url = f"{self.base_url}/api/v1/verify"
response = self.session.post(url, json={
'registrationId': registration_id,
'type': 'musical_work',
'content': content
})
response.raise_for_status()
return response.json()
def check_status(self, verification_id):
"""Check verification status"""
url = f"{self.base_url}/api/v1/status/{verification_id}"
response = self.session.get(url)
response.raise_for_status()
return response.json()
def get_report(self, verification_id):
"""Retrieve verification report"""
url = f"{self.base_url}/api/v1/report/{verification_id}"
response = self.session.get(url)
response.raise_for_status()
return response.json()
def verify_and_wait(self, registration_id, content, poll_interval=5):
"""Submit verification and wait for completion"""
# Submit
result = self.submit_verification(registration_id, content)
verification_id = result['verificationId']
print(f"Verification submitted: {verification_id}")
# Poll for completion
while True:
status = self.check_status(verification_id)
print(f"Status: {status['status']} - {status['progress']}%")
if status['status'] == 'completed':
break
elif status['status'] == 'failed':
raise Exception("Verification failed")
time.sleep(poll_interval)
# Get report
return self.get_report(verification_id)
# Usage
client = AIVerificationClient(
'https://ai.copyrightchains.com',
'your-session-cookie'
)
with open('audio.mp3', 'rb') as f:
audio_data = base64.b64encode(f.read()).decode()
content = {
'title': 'My Song',
'files': {
'audio': audio_data
},
'metadata': {
'duration': 180,
'format': 'mp3',
'bitrate': 320
}
}
report = client.verify_and_wait('registration-uuid', content)
print(f"Overall Risk: {report['report']['overallRisk']}")
print(f"Recommendation: {report['report']['recommendation']}")
Best Practices
API Usage Guidelines
- Poll Responsibly: Use 5-10 second intervals when checking status
- Handle Timeouts: Implement exponential backoff for retries
- Validate Input: Check file sizes and formats before submission
- Cache Results: Store reports to avoid redundant requests
- Monitor Errors: Log and handle all error responses appropriately
- Respect Rate Limits: Stay within 100 requests/hour limit
Common Mistakes to Avoid
- Don't poll status continuously - use reasonable intervals
- Don't submit files over size limits - validate first
- Don't ignore error responses - handle all status codes
- Don't forget credentials: 'include' in fetch requests
Error Codes
Complete reference of API error codes:
| Code | Status | Description |
|---|---|---|
| AUTH_REQUIRED | 401 | No valid session found |
| INSUFFICIENT_PERMISSIONS | 403 | Admin access required |
| INVALID_REQUEST | 400 | Malformed request data |
| NOT_FOUND | 404 | Resource not found |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
| FILE_TOO_LARGE | 413 | File exceeds size limit |
| PROVIDER_ERROR | 502 | AI provider failed |
| SERVER_ERROR | 500 | Internal server error |