Authentication

All requests to the Spellbreaker API must be authenticated using secure, token-based authentication. This ensures robust, scalable access control to our deepfake detection services.

Overview of Authentication Flow

1. Clients authenticate with server and obtain a api token.
2. Clients include this token in the Authorization header when calling any protected API endpoint.
3. API Gateway validates the token before forwarding the request to the backend.

Getting Access

To gain access to the Spellbreaker API:

1. Sign up for a subscription account on Spellbreaker.
2. Navigate to your dashboard and access the API Keys section.
3. Create a new API key by providing a name and optionally configuring IP and domain restrictions.
4. Copy your API key immediately after creation - you won't be able to see the full token again.

Token-Based Authentication

Once authenticated, your client will receive a api token. These tokens are valid till you revoke them.

Include this token in the Authorization header of all API requests:

The token is automatically validated by our API Gateway before any request is forwarded to the inference engine.

Example (Python + Token)

import requests

API_TOKEN = 'your_api_token_here'
API_URL = 'https://app.spellbreaker.ai/api/v1.0/deepfake/68ee18fbbf286d24fd9bdbdc/status'

headers = {
'Authorization': f'Bearer {API_TOKEN}'
}

response = requests.get(API_URL, headers=headers)

if response.ok:
  print("Success:", response.json())
else:
  print("Error:", response.status_code, response.text)

Security Best Practices

• Never expose your token in frontend JavaScript or public repositories.
• Rotate credentials periodically.
• Use third-party tools like SecurityScorecard to regularly assess the security posture of your application.

Upload Media

The POST api/v1.0/media/upload endpoint allows you to upload video, audio or image files for deepfake forensic inspection. This is the first step in the Spellbreaker detection pipeline.

You can upload videos, audio or images for forensic evaluation.

Endpoint

Authentication

This endpoint requires a valid API key. Include it in the Authorization header. Tokens are valid until you revoke them:

Supported Media Types

• Video .mp4 .mkv .avi .mov .wmv .flv .webm
• Audio .mp3 .wav .aac .flac .aif .aiff .ogg .m4a
• Image .jpg .png .bmp .tiff .webp

Headers

Request Body

Code Example

cURL

curl -X POST https://app.spellbreaker.ai/api/v1.0/media/upload \
  -H "Authorization: Bearer <your_api_token_here>" \
  -F "file=@/path/to/your/video.mp4" \
  -F "fileHash=<sha256_hash_of_the_file>"

Success Response

{
  "statusCode": 0,
  "data": {
    "referenceId": "692a9390e18c3d5e423c5cb8"
  }
}

Error Responses

All endpoints return these common error responses:

400 Bad Request

{
  "statusCode": -9999,
  "message": "Unsupported file extension. Allowed extensions: .mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, .mp3, .wav, .aac, .flac, .aif, .aiff, .ogg, .m4a, .jpg, .jpeg, .png, .bmp, .tiff, .webp"
}

400 Bad Request

{
  "statusCode": -9999,
  "message": "The file is not a valid image file. It may be corrupted, or its content may not match the .jpg extension."
}

403 Forbidden

{
  "statusCode": -9999,
  "message": "User not found"
}

400 Bad Request

{
  "statusCode": -9999,
  "message": "File size exceeds the limit for image"
}

Next Step

Once uploaded, use the returned referenceId to perform media inspection:

Developer Notes

• Large media file may fail to upload depending on server-side configuration.
• Files are checked on upload: the content must be a readable image, audio or video file that matches its extension. A renamed, empty or damaged file is refused with 400 before any analysis starts.
• After uploading, you will receive a referenceId used in subsequent API calls (inspect, status, get report, etc.).

Media Inspection

Once a media file is successfully uploaded via the Upload Media Endpoint, you can initiate a forensic deepfake analysis using the Media Inspection endpoint.

We only store the hash of the file and the forensic report. The media file is deleted after certain number of days after inspection as configured on the server.

Once a media file is successfully uploaded using the Upload Media Endpoints, you can initiate deepfake analysis by calling the dedicated inspection endpoint for the specific media type and providing the referenceId in the request body.

There are separate endpoints to trigger the inspection process for the uploaded media.

1. Initiate Media Inspection

The POST api/v1.0/deepfake/start endpoint triggers the deepfake analysis pipeline for a previously uploaded media.

Endpoint

Authentication

This endpoint requires a valid API key. Include it in the Authorization header. Tokens are valid until you revoke them:

Request Body

With noReport, the analysis runs as usual and the status endpoints return the verdict and its confidence, but no report is produced: reportUrl and reportFileHash stay null. The report cannot be produced later without running the analysis again, so use it only if your integration reads the verdict from the API and never opens the report.

Content-Type: application/json

Code Example

cURL

curl -X POST https://app.spellbreaker.ai/api/v1.0/deepfake/start \
  -H "Authorization: Bearer <your_api_token_here>" \
  -H "Content-Type: application/json" \
  -d '{"referenceId": "68ee18fbbf286d24fd9bdbdc"}'

Code Example (verdict only, no report)

curl -X POST https://app.spellbreaker.ai/api/v1.0/deepfake/start \
  -H "Authorization: Bearer <your_api_token_here>" \
  -H "Content-Type: application/json" \
  -d '{"referenceId": "68ee18fbbf286d24fd9bdbdc", "noReport": true}'

Success Response (Inspection Initiated)

{
  "statusCode": 0,
  "data": {
    "status": "queued"
  }
}

Missing referenceId

{
  "statusCode": -9999,
  "message": "referenceId should not be empty"
}

Invalid referenceId

{
  "statusCode": -9999,
  "message": "Media not found"
}

Unauthorized Token

{
  "statusCode": -9999,
  "message": "Invalid API token"
}

2. Check Inspection Status

Use these endpoints to monitor the progress of your deepfake analysis tasks. Three status check options are available depending on your use case.

2.1 Single Task Status

Check the status of a specific analysis task by its reference ID.

Authentication:

Example Request:

curl -X GET "https://app.spellbreaker.ai/api/v1.0/deepfake/692a8a6aec7dd33fcf9feb52/status" \
  -H "Authorization: Bearer <your_api_token_here>"

Success Response

{
  "statusCode": 0,
  "data": {
    "referenceId": "692a8a6aec7dd33fcf9feb52",
    "status": "done",
    "reportUrl": "https://app.spellbreaker.ai/api/v1.0/reports/39f39266-6deb-48e4-924d-21d12d76fc06.pdf",
    "reportFileHash": "50f0737dbebc69861353a6000c94ddd56029938c9c117df7abc4a1645d8abab0",
    "result": "fake",
    "confidence": 0.9412,
    "reason": "Analysis completed successfully",
    "errorCode": null,
    "mimeType": "image/png",
    "originalName": "avatar.png",
    "createdAt": "2025-11-29T05:53:46.782Z",
    "updatedAt": "2025-11-29T05:59:15.561Z"
  }
}

2.2 Bulk Status Check

Check the status of multiple tasks simultaneously by providing comma-separated reference IDs.

Query Parameters:

Example Request:

curl -X GET "https://app.spellbreaker.ai/api/v1.0/deepfake/status?referenceIds=692a8a6aec7dd33fcf9feb52,692a9390e18c3d5e423c5cb8" \
  -H "Authorization: Bearer <your_api_token_here>"

Success Response (Array)

{
  "statusCode": 0,
  "data": [
    {
      "referenceId": "692a8a6aec7dd33fcf9feb52",
      "status": "done",
      "reportUrl": "https://app.spellbreaker.ai/api/v1.0/reports/39f39266-6deb-48e4-924d-21d12d76fc06.pdf",
      "reportFileHash": "50f0737dbebc69861353a6000c94ddd56029938c9c117df7abc4a1645d8abab0",
      "result": "fake",
      "confidence": 0.9412,
      "reason": "Analysis completed successfully",
      "errorCode": null,
      "mimeType": "image/png",
      "originalName": "avatar.png",
      "createdAt": "2025-11-29T05:53:46.782Z",
      "updatedAt": "2025-11-29T05:59:15.561Z"
    },
    {
      "referenceId": "692a9390e18c3d5e423c5cb8",
      "status": "processing",
      "reportUrl": null,
      "reportFileHash": null,
      "result": null,
      "confidence": null,
      "reason": null,
      "errorCode": null,
      "mimeType": "video/mp4",
      "originalName": "sample_video.mp4",
      "createdAt": "2025-11-29T06:12:30.123Z",
      "updatedAt": "2025-11-29T06:12:35.456Z"
    }
  ]
}

2.3 Reading the Verdict

When status is "done", result carries the verdict and confidence carries how strongly the analysis supports it, as a value between 0 and 1. The same numbers appear in the PDF report, so a threshold applied to the API gives the same decision as the report. No report download is needed to read the verdict.

Which detection models ran, and what each scored, is internal and is not returned by the API. The models in the ensemble change over time; confidence is the value to build logic on.

2.4 Failed Analyses

When status is "failed", errorCode tells you why and reason is a short message you can show to your users. Use errorCode in your code, since the reason wording may change.

Example Response (Failed)

{
  "statusCode": 0,
  "data": {
    "referenceId": "692a9390e18c3d5e423c5cb8",
    "status": "failed",
    "reportUrl": null,
    "reportFileHash": null,
    "result": null,
    "confidence": null,
    "reason": "The file could not be read as a valid image, audio or video file. Please check the file and upload it again.",
    "errorCode": "INVALID_MEDIA",
    "mimeType": "image/jpeg",
    "originalName": "evidence.jpg",
    "createdAt": "2025-11-29T06:12:30.123Z",
    "updatedAt": "2025-11-29T06:15:17.456Z"
  }
}

3. Stop Running Task

Cancel a queued or processing analysis task. Useful for stopping long-running analyses or correcting mistakes.

Authentication:

Request Body:

Example Request:

curl -X POST "https://app.spellbreaker.ai/api/v1.0/deepfake/stop" \
  -H "Authorization: Bearer <your_api_token_here>" \
  -H "Content-Type: application/json" \
  -d '{"referenceId": "692a9390e18c3d5e423c5cb8"}'

Success Response

{
  "statusCode": 0,
  "data": {
    "status": "stopped"
  }
}

4. Get User Statistics

Retrieve aggregate statistics for your account, including total scans, completed analyses, and status breakdown.

Authentication Note:

This endpoint requires your email in the Authorization header (API tokens are not supported for this endpoint).

Example Request:

curl -X GET "https://app.spellbreaker.ai/api/v1.0/deepfake/stats" \
  -H "Authorization: Bearer your_email@example.com"

Success Response

{
  "statusCode": 0,
  "data": {
    "totalScans": 125,
    "completedScans": 118,
    "queuedScans": 2,
    "processingScans": 1,
    "failedScans": 3,
    "stoppedScans": 1
  }
}

Security & Best Practices

• API tokens are valid until you revoke them via the dashboard or API
• Media files are automatically deleted after a configured retention period (server-side)
• Only SHA-256 file hashes and analysis reports are permanently stored
• Use reportFileHash to verify report integrity
• Poll status endpoints at reasonable intervals (recommended: every 5-10 seconds)
• Use the bulk status endpoint for checking multiple tasks efficiently

Generate Report

After media inspection is complete (status is done ), a detailed forensic report is available for download. The report includes classification results (real/fake), confidence scores, technical analysis details and visual evidence.

Endpoint

The reportUrl is returned in the status API response when the analysis is complete. This URL already contains the filename. Request it with the same Authorization header you use for the rest of the API.

Authentication

Send your API token as a Bearer token in the Authorization header, the same as every other endpoint:

An apitoken query parameter is also accepted, but avoid it for server-to-server calls: URLs are often written to server and proxy logs.

Code Example

cURL - Download Report

curl -X GET "https://app.spellbreaker.ai/api/v1.0/reports/f3a1754b-3329-4851-8ec8-10df78beac2a.pdf" \
  -H "Authorization: Bearer <your_api_token_here>" \
  -H "Accept: application/pdf" \
  -o report.pdf

Response

Success (200 OK)

Returns a binary stream of the report file (typically PDF). The response includes:

• Content-Type: application/pdf
• Content-Length: File size in bytes
• Content-Disposition: inline; filename="..."

%PDF-1.7
1 0 obj
...binary PDF data...
%%EOF

Error Responses

Developer Notes

• All uploaded files are deleted after a configured retention period; only SHA256 hashes and reports are stored
• Use reportFileHash to verify report integrity after download
• Reports contain classification results (real/fake), confidence scores and detailed analysis

Common Error Codes

Best Practices for API Integration

• Validate files locally: Check file type and size before uploading to save bandwidth
• Calculate hash accurately: Use SHA-256 on the exact bytes being uploaded
• Implement exponential backoff: When polling status, increase interval on repeated checks
• Handle all status codes: Implement proper error handling for each HTTP status code
• Store referenceIds: Keep track of referenceIds for future status checks
• Verify report integrity: Always validate reportFileHash after download
• Use bulk endpoints: Check multiple tasks at once with the bulk status endpoint
• Secure your tokens: Never expose API tokens in client-side code or public repositories