docs/API_DOCUMENTATION.md

API Documentation

Base Information

Base URL: http://localhost:8005
API Version: 2.0.0
Protocol: HTTP/HTTPS
Content Type: application/json (default)
Architecture: Two-tier evidence-first decision system

---

Table of Contents

1. Authentication
2. Health Check
3. Single Image Analysis
4. Batch Image Analysis
5. Batch Progress Tracking
6. Report Export
7. Error Handling
8. Rate Limits
9. Data Models
10. Evidence-First Decision Policy
11. Usage Examples

---

Authentication

Current Version: No authentication required (intended for internal deployment)

Future Versions: API key authentication planned

# Planned header format
Authorization: Bearer <api_key>

---

Health Check

GET /health

Check if the API server is operational.

Request

curl -X GET http://localhost:8005/health

Response (200 OK)

{
  "status": "ok",
  "version": "1.0.0"
}

---

Single Image Analysis

POST /analyze/image

Analyze a single image for AI-generation indicators.

Request

curl -X POST http://localhost:8005/analyze/image \
  -F "file=@/path/to/image.jpg"

Parameters

Name	Type	Required	Description
file	File	Yes	Image file (JPG/PNG/WEBP, max 10MB)

Response (200 OK)

{
  "success": true,
  "message": "Image analysis completed",
  "data": {
    "filename": "example.jpg",
    "status": "REVIEW_REQUIRED",
    "final_decision": "SUSPICIOUS_AI_LIKELY",
    "decision_explanation": "Strong AI evidence detected in metadata analysis",
    "overall_score": 0.73,
    "confidence": 73,
    "evidence": [
      {
        "source": "exif",
        "finding": "AI software fingerprint detected in EXIF data",
        "direction": "ai_generated",
        "strength": "strong",
        "confidence": 0.92,
        "analyzer": "exif_analyzer",
        "timestamp": "2024-12-19T14:32:15.123456"
      }
    ],
    "signals": [
      {
        "name": "Gradient Field PCA",
        "metric_type": "gradient",
        "score": 0.81,
        "status": "flagged",
        "explanation": "Detected irregular gradient patterns..."
      }
    ],
    "metric_results": {
      "gradient": {
        "metric_type": "gradient",
        "score": 0.81,
        "confidence": 0.87,
        "details": {
          "eigenvalue_ratio": 0.72,
          "gradient_vectors_sampled": 10000
        }
      }
    },
    "processing_time": 2.34,
    "image_size": [1920, 1080],
    "timestamp": "2024-12-19T14:32:15.123456"
  },
  "timestamp": "2024-12-19T14:32:15.123456"
}

Final Decision Values

• CONFIRMED_AI_GENERATED: Conclusive evidence of AI generation

• SUSPICIOUS_AI_LIKELY: Strong evidence or high statistical metrics

• AUTHENTIC_BUT_REVIEW: Conflicting or weak evidence

• MOSTLY_AUTHENTIC: Strong authentic evidence

Status Values (Tier-1 only)

• LIKELY_AUTHENTIC: Statistical score < 0.65

• REVIEW_REQUIRED: Statistical score >= 0.65

Signal Status Values

• passed: Score < 0.40

• warning: Score >= 0.40 and < 0.70

• flagged: Score >= 0.70

---

Batch Image Analysis

POST /analyze/batch

Analyze multiple images in a single request with parallel processing.

Request

curl -X POST http://localhost:8005/analyze/batch \
  -F "files=@image1.jpg" \
  -F "files=@image2.png" \
  -F "files=@image3.webp"

Parameters

Name	Type	Required	Description
files	File[]	Yes	Multiple image files (max 50 per batch)

Response (200 OK)

{
  "success": true,
  "message": "Batch analysis completed",
  "data": {
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "result": {
      "total_images": 3,
      "processed": 3,
      "failed": 0,
      "results": [
        {
          "filename": "image1.jpg",
          "status": "REVIEW_REQUIRED",
          "final_decision": "SUSPICIOUS_AI_LIKELY",
          "decision_explanation": "Strong evidence detected...",
          "overall_score": 0.73,
          "confidence": 73,
          "evidence": [],
          "signals": [],
          "processing_time": 2.1,
          "image_size": [1920, 1080],
          "timestamp": "2024-12-19T14:32:15.123456"
        }
      ],
      "summary": {
        "CONFIRMED_AI_GENERATED": 0,
        "SUSPICIOUS_AI_LIKELY": 1,
        "AUTHENTIC_BUT_REVIEW": 1,
        "MOSTLY_AUTHENTIC": 1,
        "success_rate": 100,
        "processed": 3,
        "failed": 0,
        "avg_score": 0.510,
        "avg_confidence": 51,
        "avg_proc_time": 2.10
      },
      "total_processing_time": 6.3,
      "timestamp": "2024-12-19T14:32:19.345678"
    }
  },
  "timestamp": "2024-12-19T14:32:19.345678"
}

Batch Constraints

• Maximum images per batch: 50
• Maximum file size per image: 10 MB
• Timeout per image: 30 seconds
• Total batch timeout: 15 minutes

---

Batch Progress Tracking

GET /batch/{batch_id}/progress

Track the progress of a batch analysis job.

Request

curl -X GET http://localhost:8005/batch/550e8400-e29b-41d4-a716-446655440000/progress

Response - Processing (200 OK)

{
  "status": "processing",
  "progress": {
    "current": 7,
    "total": 10,
    "filename": "image_007.jpg"
  }
}

Response - Completed (200 OK)

{
  "status": "completed",
  "progress": {
    "current": 10,
    "total": 10,
    "filename": "image_010.jpg"
  },
  "result": {
    "total_images": 10,
    "processed": 10,
    "failed": 0,
    "results": [],
    "summary": {},
    "total_processing_time": 21.4,
    "timestamp": "2024-12-19T14:35:22.123456"
  }
}

Response - Failed (200 OK)

{
  "status": "failed",
  "error": "Processing timeout exceeded"
}

Status Values

• processing: Batch is currently being analyzed
• completed: All images processed successfully
• failed: Batch processing encountered fatal error
• interrupted: Processing was manually stopped

---

Report Export

CSV Export

GET /report/csv/{batch_id} or POST /report/csv/{batch_id}

Download detailed batch analysis as CSV file.

Request

curl -X GET http://localhost:8005/report/csv/550e8400-e29b-41d4-a716-446655440000 \
  -o report.csv

Response

• Content-Type: text/csv
• File download with comprehensive analysis data
• Includes: per-image results, metric breakdowns, forensic details

CSV Structure

BATCH DECISION STATISTICS
Total Images,10
Processed,10
Failed,0
CONFIRMED_AI_GENERATED,2
SUSPICIOUS_AI_LIKELY,3
AUTHENTIC_BUT_REVIEW,3
MOSTLY_AUTHENTIC,2

ANALYSIS RESULTS
Filename,Final Decision,Decision Confidence (%),Overall Score,Decision Explanation,Processing Time (s)
image1.jpg,SUSPICIOUS_AI_LIKELY,73,0.73,Strong evidence detected...,2.1

IMAGE 1 DETAILED ANALYSIS
FINAL DECISION
Decision,SUSPICIOUS_AI_LIKELY
Confidence,73%
Explanation,Strong evidence detected...

EVIDENCE SUMMARY
Source,Direction,Strength,Confidence,Finding
exif,ai_generated,strong,0.92,AI software fingerprint detected

---

Error Handling

Error Response Format

All errors return a standardized JSON structure:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message",
  "timestamp": "2024-12-19T14:32:15.123456"
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid input (file format, size, etc.)
404	Not Found	Batch ID not found
413	Payload Too Large	File size exceeds 10MB
422	Unprocessable Entity	Validation error
499	Client Closed Request	Processing interrupted
500	Internal Server Error	Server-side processing error

Common Error Scenarios

File Too Large

{
  "success": false,
  "message": "Validation error",
  "error": "File size 12582912 bytes exceeds maximum 10485760 bytes",
  "timestamp": "2024-12-19T14:32:15.123456"
}

Unsupported Format

{
  "success": false,
  "message": "Validation error",
  "error": "File extension .gif not allowed. Allowed: .jpg, .jpeg, .png, .webp",
  "timestamp": "2024-12-19T14:32:15.123456"
}

Batch Not Found

{
  "success": false,
  "message": "Batch not found",
  "error": null,
  "timestamp": "2024-12-19T14:32:15.123456"
}

Processing Timeout

{
  "success": false,
  "message": "Processing timeout",
  "error": "Image analysis exceeded 30 second timeout",
  "timestamp": "2024-12-19T14:32:45.123456"
}

---

Rate Limits

Current Version: No rate limiting implemented

Recommended Production Limits:

• Single image analysis: 60 requests/minute per IP
• Batch analysis: 10 requests/minute per IP
• Report downloads: 30 requests/minute per IP

---

Data Models

APIResponse

{
  success: boolean,
  message: string,
  data: object | null,
  error: string | null,
  timestamp: string
}

AnalysisResult

{
  filename: string,
  status: "LIKELY_AUTHENTIC" | "REVIEW_REQUIRED",
  final_decision: "CONFIRMED_AI_GENERATED" | "SUSPICIOUS_AI_LIKELY" | 
                  "AUTHENTIC_BUT_REVIEW" | "MOSTLY_AUTHENTIC" | null,
  decision_explanation: string | null,
  overall_score: number,      // 0.0 - 1.0
  confidence: number,         // 0 - 100
  signals: DetectionSignal[],
  evidence: EvidenceResult[],
  metric_results: {
    [key: string]: MetricResult
  },
  processing_time: number,    // seconds
  image_size: [number, number],
  timestamp: string
}

EvidenceResult

{
  source: "exif" | "watermark",
  finding: string,
  direction: "ai_generated" | "authentic" | "indeterminate",
  strength: "weak" | "moderate" | "strong" | "conclusive",
  confidence: number | null,   // 0.0 - 1.0
  details: object,
  analyzer: string,
  timestamp: string
}

DetectionSignal

{
  name: string,
  metric_type: "gradient" | "frequency" | "noise" | "texture" | "color",
  score: number,        // 0.0 - 1.0
  status: "passed" | "warning" | "flagged",
  explanation: string
}

MetricResult

{
  metric_type: "gradient" | "frequency" | "noise" | "texture" | "color",
  score: number,        // 0.0 - 1.0
  confidence: number,   // 0.0 - 1.0
  details: object       // Metric-specific forensic data
}

BatchAnalysisResult

{
  total_images: number,
  processed: number,
  failed: number,
  results: AnalysisResult[],
  summary: {
    CONFIRMED_AI_GENERATED: number,
    SUSPICIOUS_AI_LIKELY: number,
    AUTHENTIC_BUT_REVIEW: number,
    MOSTLY_AUTHENTIC: number,
    success_rate: number,
    processed: number,
    failed: number,
    avg_score: number,
    avg_confidence: number,
    avg_proc_time: number
  },
  total_processing_time: number,
  timestamp: string
}

---

Evidence-First Decision Policy

Decision Hierarchy

• Conclusive Evidence → CONFIRMED_AI_GENERATED

• Strong AI Evidence → SUSPICIOUS_AI_LIKELY

• Strong Authentic Evidence → MOSTLY_AUTHENTIC

• Conflicting/Weak Evidence → AUTHENTIC_BUT_REVIEW

• No Evidence → Fallback to statistical metrics

Evidence Strength Definitions

• CONCLUSIVE: Cryptographic proof, signed metadata

• STRONG: Clear AI fingerprints, consistent patterns

• MODERATE: Suggestive indicators, plausible patterns

• WEAK: Heuristic hints, non-binding observations

---

Usage Examples

Python

import requests

# Single image analysis
with open('image.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:8005/analyze/image',
        files={'file': f}
    )
    result = response.json()
    print(f"Final Decision: {result['data']['final_decision']}")

# Batch analysis
files = [
    ('files', open('img1.jpg', 'rb')),
    ('files', open('img2.png', 'rb'))
]
response = requests.post(
    'http://localhost:8005/analyze/batch',
    files=files
)
batch_result = response.json()
batch_id = batch_result['data']['batch_id']

# Check progress
progress = requests.get(f'http://localhost:8005/batch/{batch_id}/progress').json()

# Download CSV report
csv_response = requests.get(f'http://localhost:8005/report/csv/{batch_id}')
with open('report.csv', 'wb') as f:
    f.write(csv_response.content)

JavaScript (Node.js)

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

// Single image analysis
const form = new FormData();
form.append('file', fs.createReadStream('image.jpg'));

axios.post('http://localhost:8005/analyze/image', form, {
  headers: form.getHeaders()
})
.then(response => {
  console.log('Final Decision:', response.data.data.final_decision);
  console.log('Evidence found:', response.data.data.evidence.length);
});

// Batch progress tracking
async function trackProgress(batchId) {
  const response = await axios.get(`http://localhost:8005/batch/${batchId}/progress`);
  console.log(`Progress: ${response.data.progress.current}/${response.data.progress.total}`);
  
  if (response.data.status === 'processing') {
    setTimeout(() => trackProgress(batchId), 1000);
  } else if (response.data.status === 'completed') {
    console.log('Batch completed!');
  }
}

cURL

# Single image
curl -X POST http://localhost:8005/analyze/image \
  -F "file=@image.jpg" \
  | jq '.data.final_decision, .data.evidence[].finding'

# Batch analysis
curl -X POST http://localhost:8005/analyze/batch \
  -F "files=@img1.jpg" \
  -F "files=@img2.png" \
  | jq '.data.batch_id'

# Progress tracking
curl -X GET http://localhost:8005/batch/{batch_id}/progress \
  | jq '.status, .progress'

# CSV report
curl -X GET http://localhost:8005/report/csv/{batch_id} -o report.csv

---

Changelog

Version 1.0.0 (Current)

• Two-tier evidence-first architecture

• Four-class final decisions

• EXIF and watermark evidence analysis

• Decision policy engine

• Enhanced reporting with evidence

Planned Features

• C2PA provenance analyzer

• API key authentication

• Webhook callbacks

• Custom threshold configuration

• Real-time streaming API

---

API Documentation Version: 1.0
Last Updated: December 2025
Author: Satyaki Mitra