API Reference

Integrate Deffai AI capabilities into your existing systems and workflows

Overview

The Deffai API provides programmatic access to our AI analysis capabilities, allowing you to integrate medical device analysis into your existing quality management systems, regulatory workflows, and automated processes.

RESTful API

Standard HTTP methods

API Key Auth

Secure bearer tokens

Streaming

Real-time analysis updates

Authentication

All API requests require authentication using an API key. You can generate API keys from your dashboard settings.

Request Header

Authorization: Bearer axle_your_api_key_here

Security Note

Never expose your API key in client-side code. Always make API calls from your backend server.

Core API Endpoints

FDA Filing Management

POST /api/filingsCreate

Create a new FDA filing document record

Request Body

{
  "name": "510(k) Submission - Device XYZ",
  "documentUrl": "https://example.com/document.pdf",
  "originalFileName": "device-xyz-510k.pdf",
  "metadata": {
    "category": "510k",
    "deviceClass": "II"
  }
}

Response

{
  "filing": {
    "id": "filing-uuid",
    "name": "510(k) Submission - Device XYZ",
    "documentUrl": "https://example.com/document.pdf",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

GET /api/filingsList

Get all filings for the authenticated user

Analysis Operations

POST /api/analysesCreate

Create a new analysis with AI agent scores

Request Body

{
  "projectId": "project-uuid",
  "clinicalAgentScore": 8.5,
  "opsAgentScore": 7.2,
  "regulatoryAgentScore": 9.0,
  "consensusScore": 8.2,
  "finalRecommendation": "Device meets FDA requirements...",
  "fdaApprovalLikelihood": 8.5,
  "patientSafetyScore": 9.2,
  "sendEmail": true,
  "userEmail": "user@example.com"
}

GET /api/analysesList

Get analyses with optional filtering

Query Parameters

• type - Filter by project type (fda_filing, operations, monitoring)
• limit - Maximum results (default: 10)

GET /api/analyses/compareCompare

Compare multiple analyses for the same filing

Real-time Analysis (Server-Sent Events)

POST /api/analyze/fda-filingStreaming

Analyze FDA filing documents with real-time progress updates

Form Data

• file - The FDA filing document to analyze
• filingId - (Optional) Existing filing ID

Response (Server-Sent Events)

data: {"type":"progress","percentage":50}
data: {"type":"score","agent":"clinical","score":8.5}
data: {"type":"complete","analysisId":"analysis-uuid","scores":{...}}

Confidence Assessment

POST /api/confidence/assessmentsCreate

Create confidence assessment using fuzzy logic

Request Body

{
  "analysisId": "analysis-uuid",
  "agentType": "clinical",
  "scores": {
    "clinical": 8.5,
    "ops": 7.2,
    "regulatory": 9.0
  },
  "content": "Full document content...",
  "fileSize": 512000,
  "hasImages": true
}

Export & Reports

GET /api/analyses/{id}/exportPDF

Export analysis as a scientific report PDF

Response

Returns PDF file for download

Rate Limits & Best Practices

Rate Limiting

• Standard endpoints: 100 requests per minute
• Analysis endpoints: 1000 requests per hour
• Response headers: X-RateLimit-Remaining, X-RateLimit-Reset

Best Practices

• Use API keys securely - never expose in client-side code
• Implement exponential backoff for retries
• Cache analysis results when appropriate
• Use streaming endpoints for real-time updates
• Include proper error handling for all requests

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

400 Bad RequestInvalid request parameters

{"error": "Project ID is required"}

401 UnauthorizedMissing or invalid API key

{"error": "Unauthorized"}

404 Not FoundResource not found

{"error": "Analysis not found"}

500 Internal Server ErrorServer-side error

{"error": "Failed to create analysis"}

Quick Start Examples

Complete FDA Filing Analysis Flow

# 1. Create a filing
FILING_ID=$(curl -X POST https://Deffai.com/api/filings \
  -H "Authorization: Bearer axle_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "510(k) Submission - Device XYZ",
    "documentUrl": "https://example.com/device-xyz-510k.pdf",
    "originalFileName": "device-xyz-510k.pdf"
  }' | jq -r '.filing.id')

# 2. Create a project
PROJECT_ID=$(curl -X POST https://Deffai.com/api/projects \
  -H "Authorization: Bearer axle_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FDA Analysis - Device XYZ",
    "type": "fda_filing",
    "filingId": "'$FILING_ID'"
  }' | jq -r '.project.id')

# 3. Create an analysis
ANALYSIS_ID=$(curl -X POST https://Deffai.com/api/analyses \
  -H "Authorization: Bearer axle_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'$PROJECT_ID'",
    "clinicalAgentScore": 8.5,
    "opsAgentScore": 7.2,
    "regulatoryAgentScore": 9.0,
    "consensusScore": 8.2,
    "finalRecommendation": "Device meets FDA requirements",
    "fdaApprovalLikelihood": 8.5,
    "patientSafetyScore": 9.2
  }' | jq -r '.analysis.id')

# 4. Export as PDF
curl -X GET https://Deffai.com/api/analyses/$ANALYSIS_ID/export \
  -H "Authorization: Bearer axle_your_api_key" \
  -o "analysis-report.pdf"

JavaScript - Real-time Analysis

// Submit FDA filing for real-time analysis
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const eventSource = new EventSource('/api/analyze/fda-filing', {
  method: 'POST',
  body: formData,
  headers: {
    'Authorization': 'Bearer axle_your_api_key'
  }
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'progress':
      console.log(`Progress: ${data.percentage}%`);
      break;
    case 'score':
      console.log(`${data.agent} score: ${data.score}`);
      break;
    case 'complete':
      console.log('Analysis complete!', data);
      eventSource.close();
      break;
  }
};

Python - Batch Analysis

import requests
import json

# Compare multiple analyses for a filing
url = "https://Deffai.com/api/analyses/compare"
headers = {
    "Authorization": "Bearer axle_your_api_key"
}
params = {
    "filingId": "filing-uuid"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Average Consensus Score: {data['averageConsensusScore']}")
print(f"Total Analyses: {data['count']}")

# Display individual scores
for analysis in data['analyses']:
    print(f"\nAnalysis {analysis['id']}:")
    print(f"  Clinical: {analysis['clinicalScore']}")
    print(f"  Ops: {analysis['opsScore']}")
    print(f"  Regulatory: {analysis['regulatoryScore']}")
    print(f"  Consensus: {analysis['consensusScore']}")

Get Started with the API

Generate your API key from the dashboard and start integrating Deffai into your workflows.

Generate API Key View Documentation