Analysis API

The Analysis API provides endpoints for creating, retrieving, retrying, exporting, and deleting forensic media analyses.

Quick Reference

• Analysis types: image (JPEG, PNG)
• Tiers: "flagging" (result class only) or "forensicReporting" (full forensic data including heatmaps, predictions, texts)
• Image formats: jpg, png
• Result classes: real, fake, uncertain, abstain
• Inference statuses: pending, processing, completed, failed
• Storage backends: S3-compatible or Azure Blob Storage with presigned URLs
• Presigned URL expiry: Configurable per-tenant

See Data Model for detailed specifications.

Workflow

Analysis Lifecycle

stateDiagram-v2
    [*] --> Created: POST /v1/analysis
    Created --> Uploaded: PUT image to presigned URL
    Uploaded --> Pending: POST /v1/analysis/start
    Pending --> Processing: Inference triggered
    Processing --> Completed: Success
    Processing --> Processing: Auto-retry (up to 3x)
    Processing --> Failed: Error after retries exhausted
    Completed --> Results: GET /v1/analysis
    Results --> [*]
    Failed --> Pending: POST /v1/analysis/retry
    
    note right of Created
        Response includes presigned
        upload URL (storageUrls.putUrl)
    end note
    
    note right of Pending
        /v1/analysis/start triggers
        EXIF extraction, trial image
        validation, and inference
    end note
    
    note right of Processing
        ML inference
        Heatmap generation
        Auto-retries on error
        ---- Webhook (optional) ----
        POST to webhookUrl on
        every status transition
    end note
    
    note right of Results
        Flagging tier: resultClass + resultSubClass only
        ForensicReporting tier: full data
    end note
    
    note right of Failed
        Manual retry available
        via /v1/analysis/retry
        ---- Webhook (optional) ----
        POST to webhookUrl
    end note

Real-time Notifications

If a webhook is configured on your tenant, the API automatically sends an HTTP POST to your webhookUrl on every status transition (pending => processing => completed/failed), so you don’t need to poll GET /v1/analysis. See Webhook Management for payload details and Credential Rotation for securing your webhook endpoint.

Complete Overview of Data Models

For detailed field definitions and entity relationships, see the Data Model documentation.

Analysis resources also expose audit metadata that distinguishes the immutable creator (createdByUserId) from the latest tracked modifier (lastChangedByUserId). For user-authenticated requests these fields contain the MongoDB user ObjectId string; for API-key requests they contain the API key UUID. Read endpoints also project lastChangedByUserName, which resolves the current display name of the user referenced by lastChangedByUserId when that actor is a user.

Pagination

List endpoints support pagination:

Parameter	Type	Default	Description
start	integer	0	Zero-based offset
limit	integer	-	Max records (≥ 1)

Example:

GET /v1/analysis?tenantName=demo&start=10&limit=25

Search

Some endpoints support text search:

GET /v1/analysis?tenantName=demo&searchTerm=suspicious

The search term is case-insensitive and matches against relevant fields such as the analysis name, comment, and projected last-changed user name.

Data Types

For complete data model documentation including entity relationships, field definitions, and validation rules, see the Data Model reference.