ProbeTruth Documentation

Authentication

All requests to the ProbeTruth 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 ProbeTruth API:

1. Sign up for a subscription account on ProbeTruth.
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.probetruth.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 ProbeTruth 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
• Image .jpg .png .bmp .tiff

Headers

Request Body

Code Example

cURL

curl -X POST https://app.probetruth.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, .jpg, .jpeg, .png, .bmp, .tiff"
}

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.
• Accepted media types are validated on the backend. If you're unsure, validate the file type before uploading.
• 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

Content-Type: application/json

Code Example

cURL

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

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.probetruth.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.probetruth.ai/api/v1.0/reports/39f39266-6deb-48e4-924d-21d12d76fc06.pdf",
    "reportFileHash": "50f0737dbebc69861353a6000c94ddd56029938c9c117df7abc4a1645d8abab0",
    "result": "Analysis completed successfully",
    "reason": 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.probetruth.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.probetruth.ai/api/v1.0/reports/39f39266-6deb-48e4-924d-21d12d76fc06.pdf",
      "reportFileHash": "50f0737dbebc69861353a6000c94ddd56029938c9c117df7abc4a1645d8abab0",
      "result": "Analysis completed successfully",
      "reason": 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,
      "reason": null,
      "mimeType": "video/mp4",
      "originalName": "sample_video.mp4",
      "createdAt": "2025-11-29T06:12:30.123Z",
      "updatedAt": "2025-11-29T06:12:35.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.probetruth.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.probetruth.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. To access the report, add your API token as a query parameter.

Authentication

Include your API token as a query parameter apiToken (alternative to Authorization header for browser downloads):

Code Example

cURL - Download Report

curl -X GET "https://app.probetruth.ai/api/v1.0/reports/f3a1754b-3329-4851-8ec8-10df78beac2a.pdf?apiToken=<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