Reference Protocol

API Reference & Webhooks

Welcome to the DeepTrace API and integration reference documentation. Build customized content verification systems and manage synthetic media detection events programmatically.

REST Endpoints Webhooks SDK References

info

Status: Model Checkpoint Pending

The core AI model checkpoint is currently training. During this period, the API will respond with HTTP 503 Service Unavailable for verification requests to ensure no false negatives or fabricated scores are delivered.

Authentication

In production environments, all requests to the DeepTrace API must be authenticated using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_DT_API_KEY

Note: Local development instances are unauthenticated by default. In production, authentication is enforced by setting the DT_API_KEY environment variable on the server.

Base URL

API requests are sent to the following base URLs depending on the environment:

Local Development http://localhost:8000

Active

Production (Cloud Managed) https://api.deeptrace.io/v1

Planned

Error Codes

The API uses standard HTTP response codes to indicate success or failure.

Code	Status	Description
200	OK	Request completed successfully.
400	Bad Request	Invalid request payload, parameters, or schema validation failure.
401	Unauthorized	Missing or invalid API token.
413	Payload Too Large	Uploaded file exceeds the maximum size limit (10MB for images, 100MB for videos).
503	Service Unavailable	Underlying model checkpoint is not loaded. DeepTrace strictly enforces a zero-fake-outputs policy: rather than returning a mocked classification, we fail with a 503 error.

503 Zero-Fake-Outputs Schema

{
  "detail": "No model loaded. Run training/train.py first."
}

Rate Limits

Rate limits are applied to prevent server overload. Limits are enforced at the client IP level.

Local Dev Unenforced

No rate limits applied. Enforced only in production deployments.

Free Tier 30 req/min

Planned for public cloud endpoints. Limits standard scan requests.

Enterprise Unlimited

Planned for self-hosted instances. Scaled dynamically by deployment hardware.

REST Endpoints

GET /api/health — System Health Check

expand_more

Retrieve active model loading states, application version, and uptime counters.

Response Schema (200 OK)

{
  "status": "ok",
  "model_loaded": true,
  "version": "0.1.0",
  "uptime_seconds": 3600
}

cURL Example

curl -X GET http://localhost:8000/api/health

Python Example

import requests
res = requests.get("http://localhost:8000/api/health")
print(res.json())

POST /api/predict/image — Scan Image

expand_more

Process an uploaded image through our deepfake detection network to output authenticity predictions and Grad-CAM target activation heatmaps.

Request Parameters

Parameter	Type	Position	Description
file	Binary	multipart/form-data	Required. The image file (jpg/png/webp, max 10MB).
use_tta	Boolean	Query	Optional. Run 8-variant test-time augmentation (default: false).

Response Schema (200 OK)

{
  "label": "fake",
  "confidence": 0.934,
  "probabilities": {
    "real": 0.066,
    "fake": 0.934
  },
  "processing_ms": 42.3,
  "gradcam_image": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}

cURL Example

curl -X POST http://localhost:8000/api/predict/image \
  -F "file=@face.jpg" \
  -F "use_tta=true"

Python Example

import requests
files = {"file": open("face.jpg", "rb")}
params = {"use_tta": True}
res = requests.post("http://localhost:8000/api/predict/image", files=files, params=params)
print(res.json())

POST /api/predict/video — Scan Video

expand_more

Process an uploaded video clip. Sample frames are extracted, scored, and aggregated using a confidence-weighted voting matrix.

Request Parameters

Parameter	Type	Position	Description
file	Binary	multipart/form-data	Required. The video file (mp4/avi/mov, max 100MB).
sample_frames	Integer	Query	Optional. Number of frames to sample (default: 16, max: 32).

Response Schema (200 OK)

{
  "prediction": "fake",
  "confidence": 0.891,
  "frame_predictions": [
    { "frame_idx": 0, "label": "fake", "prob_fake": 0.92 },
    { "frame_idx": 1, "label": "real", "prob_fake": 0.08 }
  ],
  "processing_ms": 312.7
}

cURL Example

curl -X POST http://localhost:8000/api/predict/video \
  -F "file=@clip.mp4" \
  -F "sample_frames=16"

Python Example

import requests
files = {"file": open("clip.mp4", "rb")}
params = {"sample_frames": 16}
res = requests.post("http://localhost:8000/api/predict/video", files=files, params=params)
print(res.json())

GET /api/model/info Planned — Model Details

expand_more

Retrieve architecture metadata, parameter counts, and validation metrics for the active model. **(Planned)**

Response Schema (200 OK)

{
  "architecture": "resnet18",
  "parameters": 11689512,
  "trained_on": "Celeb-DF v2"
}

cURL Example

curl -X GET http://localhost:8000/api/model/info

Python Example

import requests
res = requests.get("http://localhost:8000/api/model/info")
print(res.json())

POST /api/model/reload — Reload Checkpoint

expand_more

Swap the active weights of the neural pipeline. Reloads the predictor using the specified checkpoint path.

Request Body Schema

Field	Type	Description
checkpoint_path	String	Required. Path to the model checkpoint `.pth` file on the local disk.

Response Schema (200 OK)

{
  "status": "reloaded",
  "model_version": "checkpoints/resnet18/best.pth",
  "val_accuracy": 0.0
}

cURL Example

curl -X POST http://localhost:8000/api/model/reload \
  -H "Content-Type: application/json" \
  -d '{"checkpoint_path": "checkpoints/resnet18/best.pth"}'

Python Example

import requests
res = requests.post("http://localhost:8000/api/model/reload", json={"checkpoint_path": "checkpoints/resnet18/best.pth"})
print(res.json())

GET /api/config — Client Configuration

expand_more

Retrieve configurations loaded by the backend (e.g. backend Base URL details) required by the client frontend.

Response Schema (200 OK)

{
  "api_base_url": "",
  "version": "0.1.0"
}

cURL Example

curl -X GET http://localhost:8000/api/config

Python Example

import requests
res = requests.get("http://localhost:8000/api/config")
print(res.json())

Webhooks

Webhooks allow you to receive real-time HTTP POST notifications when specific events occur within the DeepTrace analysis pipeline. Instead of polling the REST endpoints for completion, DeepTrace pushes the completed payload directly to your configured listener.

construction

Webhooks Planned for v0.4

The webhook subsystem is under active design. The specifications below define the target implementation. Endpoints and signatures are subject to change before the final v0.4 release.

Registering a Webhook

To receive webhook events, register your endpoint URL. DeepTrace will verify the endpoint via a handshake challenge.

curl -X POST http://localhost:8000/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourdomain.com/webhooks/deeptrace",
    "events": ["scan.completed", "scan.failed"],
    "secret": "your_webhook_signing_secret"
  }'

201 Created Response Schema

{
  "id": "wh_01h7abc123",
  "url": "https://yourdomain.com/webhooks/deeptrace",
  "events": ["scan.completed", "scan.failed"],
  "secret": "your_webhook_signing_secret",
  "status": "active"
}

Event Types

The following event types are triggered by DeepTrace. Click the tabs below to view the payload schema for each event:

{
  "event": "scan.completed",
  "timestamp": 1719273600,
  "data": {
    "scan_id": "scan_992_04_x",
    "media_type": "image",
    "label": "fake",
    "confidence": 0.934,
    "probabilities": {
      "real": 0.066,
      "fake": 0.934
    }
  }
}

Signature Verification

Each webhook request contains an X-DeepTrace-Signature-256 header computed using HMAC-SHA256. Secure your endpoints by verifying the signature in constant-time:

Python (FastAPI) Verification Example

import hmac
import hashlib
from fastapi import Header, HTTPException, Request

async def verify_signature(request: Request, x_deeptrace_signature_256: str = Header(...)):
    body = await request.body()
    secret = b"your_webhook_signing_secret"
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, x_deeptrace_signature_256):
        raise HTTPException(status_code=401, detail="Invalid signature")

Node.js Verification Example

const crypto = require('crypto');

function verifySignature(req, res, next) {
    const signature = req.headers['x-deeptrace-signature-256'];
    const secret = 'your_webhook_signing_secret';
    const hash = crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');
    if (!crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature))) {
        return res.status(401).send('Invalid signature');
    }
    next();
}

Retry Logic

If your webhook server returns a non-2xx status code or times out, DeepTrace retries the delivery up to 4 times with exponential backoff:

Attempt	Delay	Strategy
1	5 seconds	First retry after failure.
2	30 seconds	Second retry after failure.
3	5 minutes	Third retry after failure.
4	30 minutes	Final attempt before dropping event.

SDK Reference

Python SDK

Integrate DeepTrace with our high-level Python client library (planned for v0.5):

pip install deeptrace-sdk

Usage Example

from deeptrace import DeepTrace

client = DeepTrace(api_key="your_api_key")

# Scan an image
result = client.scan_image("face.jpg", use_tta=True)
print(f"Prediction: {result.label} (Conf: {result.confidence})")

# Scan a video
video_result = client.scan_video("clip.mp4", sample_frames=16)
print(f"Verdict: {video_result.prediction}")

# Register a webhook
webhook = client.webhooks.create(
    url="https://yourdomain.com/webhooks",
    events=["scan.completed"]
)

Node.js SDK

Integrate DeepTrace with our JavaScript/TypeScript client library (planned for v0.5):

npm install @deeptrace/sdk

Usage Example

const { DeepTrace } = require('@deeptrace/sdk');

const client = new DeepTrace({ apiKey: 'your_api_key' });

async function run() {
    // Scan an image
    const result = await client.scanImage('face.jpg', { useTta: true });
    console.log(`Prediction: ${result.label} (Conf: ${result.confidence})`);

    // Scan a video
    const videoResult = await client.scanVideo('clip.mp4', { sampleFrames: 16 });
    console.log(`Verdict: ${videoResult.prediction}`);

    // Register a webhook
    await client.webhooks.create({
        url: 'https://yourdomain.com/webhooks',
        events: ['scan.completed']
    });
}

Ready to integrate?

Get started with our detection lab or discuss integration challenges on our repository.

Try Detection Lab Open GitHub Issue