Die Verifizierungs-API von Lumethic

Eine Foto-Verifizierungs-API nimmt ein hochgeladenes Bild entgegen, prüft es gegen die RAW-Datei der Kamera oder gegen seine Content Credentials und liefert ein signiertes Ergebnis, mit dem Ihre Anwendung arbeiten kann. Die REST-API von Lumethic tut genau das für von Nutzern hochgeladene Fotos, in jeder Menge.

Was die API leistet

Sie senden ein Foto und, wenn vorhanden, die RAW-Datei, aus der es entstanden ist. Die API prüft, ob die RAW-Datei echte Sensordaten enthält, ob das Foto dazu passt und ob die Metadaten beider Dateien zur Kamera passen, und versieht das Foto anschließend mit einem von Lumethic attestierten C2PA-Credential, das das Ergebnis festhält. Ohne RAW-Datei prüft sie die Content Credentials, die die Datei bereits trägt. Die RAW-Datei wird nur für diese Prüfung verwendet, die Verarbeitung läuft in der Europäischen Union.

Drei Endpunkte decken den Ablauf ab: POST /v1/verifications/ lädt die Dateien hoch und startet die Prüfung, GET /v1/verifications/{id} liefert Status und Ergebnis, und POST /v1/verifications/{id}/share erzeugt einen Berichtslink für Prüfende. Die vollständige Referenz weiter unten führt jeden Endpunkt mit Beispielen für Anfrage und Antwort auf; derselbe Schlüssel gilt für den MCP-Server.

Abgerechnet wird pro Verifizierung. Der kostenlose Tarif enthält 5 Verifizierungen im Monat, Basic enthält 25 für 3,95 € im Monat, Professional enthält 500 für 49,95 € im Monat, jede weitere Verifizierung kostet 0,25 €. Prüfungen eines Bildes ohne RAW-Datei sind kostenlos und zählen nicht zum Kontingent. Enterprise-Mengen werden auf Anfrage bepreist.

Erste Schritte

Registrieren

Erstellen Sie Ihr Konto, um sofortigen Zugriff zu erhalten.

Schlüssel generieren

Gehen Sie zu Ihrem Dashboard, um Ihren einzigartigen API-Schlüssel zu erstellen.

Doku lesen

Erkunden Sie unsere interaktive API-Dokumentation, um mit der Integration zu beginnen.

Lumethic aus KI-Agenten nutzen

Möchten Sie Lumethic lieber aus einem KI-Agenten statt über pures HTTP aufrufen? Unser Model-Context-Protocol-Server (MCP) ermöglicht es jedem MCP-fähigen Client, die Echtheit von Fotos über einen Streamable-HTTP-Endpunkt zu prüfen – mit demselben API-Schlüssel.

https://api.lumethic.com/mcp

MCP-Doku ansehen

Registrieren und loslegen

Ein API-Schlüssel ist für alle Anfragen erforderlich.

API Overview

Lumethic - Integration API v1.0.0 · 37 endpoints

RESTful API for photo authenticity verification. Build automated integrations with any programming language: photo management systems, DAMs, CMSs, editorial workflows, or AI agents.

Base URL: https://api.lumethic.com

Upload RAW + photo pairs (or photo-only for a C2PA check)
Verify authenticity analysis
Share shareable reports

Authentication

Header: X-API-Key: your_key

Get your API key →

File Formats

RAW: CR2, CR3, ARW, NEF, DNG, RAF, ORF, RW2, PEF, SRW (optional; omit for an image-only C2PA check)

Image (pair): JPEG, HEIF/HEIC (only these corroborate the RAW)

Image (image-only): JPEG, PNG, WebP, HEIF/HEIC, AVIF, TIFF, GIF

Pricing

Free: 5 verifications/mo

Basic: 25/mo, €3.95

Professional: 500/mo, €49.95, incl. 50 PSD exports/mo

Enterprise: volume pricing, SLA

Overage: €0.25 (negotiable at volume). Billed in EUR for eurozone billing addresses and USD elsewhere, at the same numbers. Image-only checks are free and don't count toward quota. Plans →

Quick Start

# 1. Create a verification (omit -F "raw=..." for an image-only C2PA check)
curl -X POST "https://api.lumethic.com/v1/verifications/" \
  -H "X-API-Key: your_api_key" \
  -F "raw=@photo.CR2" -F "image=@photo.jpg"

# 2. Poll for result (every 20s, timeout 10min)
curl "https://api.lumethic.com/v1/verifications/{id}" -H "X-API-Key: your_api_key"

# Response: { status, assurance_level: "verified", capture_verified: true,
#             verification_mode: "raw_pair", result: true, result_confidence: 0.95 }
# Key on assurance_level + capture_verified; the result boolean is legacy.
# result_confidence is an export-similarity average, not a probability.

Processing runs forensic analyses (RAW integrity, EXIF, sensor patterns, SSIM, histogram, recapture detection). See our whitepaper for details.

For AI Agents & Automated Integrations

Use the OpenAPI 3.1 spec to auto-generate type-safe clients:

openapi-generator generate -i https://api.lumethic.com/openapi.json -g python -o ./client
Workflow: POST /v1/verifications/ → Poll GET /v1/verifications/{id} → Read assurance_level & capture_verified

API Endpoints

Complete reference for all 37 endpoints, grouped by functionality.

Verifications

Create and manage photo authenticity verifications.

24 endpoints
GET/v1/verifications/
Auth

List Verifications

Retrieve a paginated list of photo authenticity verifications for your account.

▶View Details

Parameters

NameInType
offsetqueryinteger
sizequeryinteger
sort_byquerystring
sort_orderquerystring
searchquerystring
statusquerystring
resultquerystring
tagsquerystring
tag_matchquerystring
request_idquerystring

✓ Response 200 — Paginated list of verifications

FieldType
items*object[]
total*integer
offset*integer
size*integer
total_pages*integer
▶ Example Response
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "...",
      "results": [
        "..."
      ],
      "result": null,
      "result_confidence": null,
      "assurance_level": null,
      "assurance_reason": null,
      "verdict": null,
      "verdict_reason": null,
      "evidence_report": null,
      "verification_mode": "...",
      "capture_verified": false,
      "raw_metadata": null,
      "image_metadata": null,
      "rendition_info": null,
      "rendition_corrected_info": null,
      "raw_photo_hash": null,
      "image_photo_hash": null,
      "image_thumbnail_url": null,
      "name": null,
      "short_code": null,
      "request_id": null,
      "pipeline_build": null,
      "tags": [
        "..."
      ],
      "comment_count": 0,
      "account_id": "550e8400-e29b-41d4-a716-446655440000",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 0,
  "offset": 0,
  "size": 0,
  "total_pages": 0
}
▶ Error Responses (3)
400Invalid filter or sort parameter
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/verifications/
Auth

Create Verification

Create a new photo authenticity verification by uploading RAW and JPEG files.

▶View Details

Request Body (multipart/form-data) *

FieldType
image*string(binary)
rawstring
attestation_idstring
▶ Example Request
{
  "image": "<binary file>",
  "raw": null,
  "attestation_id": null
}

✓ Response 201 — Verification created and queued for processing

FieldType
id*string(uuid)
security_scorenumber
▶ Example Response
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
▶ Error Responses (3)
402Quota or budget limit reached
404Not found
422File hash mismatch
POST/v1/verifications/claim
Auth

Claim Verifications

Claim anonymous verifications into the authenticated account.

▶View Details

Request Body (application/json) *

FieldType
anonymous_user_id*string
▶ Example Request
{
  "anonymous_user_id": "string"
}

✓ Response 200 — Anonymous verifications claimed

FieldType
claimed*integer
verification_ids*string[]
▶ Example Response
{
  "claimed": 0,
  "verification_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
▶ Error Responses (5)
404Not found
409Already claimed by another account
410Claim window elapsed
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
429Too many claim attempts
GET/v1/verifications/{verification_id}
Auth

Get Verification

Retrieve detailed results for a specific photo verification.

▶View Details

Parameters

NameInType
verification_id*pathstring

✓ Response 200 — Verification details returned

FieldType
id*string(uuid)
psd_exportobject
anchored_inobject[]
status*"pending" | "queued" | "in_progress" | "completed" | "failed"
failure_reasonstring
results*object[]
result*boolean
result_confidence*number
assurance_level"verified" | "provisional" | "provenance" | "unrated" | "flagged"
assurance_reasonstring
verdict"ai_declared" | "modified_after_signing" | "provenance_verified" | "self_declared_ai" | "unrated"
verdict_reason"watermark_detected" | "c2pa_generative_declared" | "tampered" | "invalid_signature" | "c2pa_trusted_capture" | "untrusted_signer_generative" | "iptc_digital_source_type" | "generator_metadata" | "container_signature" | "untrusted_signer" | "trust_unverified" | "no_capture_claim" | "no_trusted_timestamp" | "unlisted_actions_present" | "computational_capture_only" | "unrated_indeterminate" | "unrated_reviewed_clean" | "unrated_no_evidence"
evidence_reportobject
verification_mode"raw_pair" | "image_only"
capture_verifiedboolean
raw_metadata*object
image_metadata*object
rendition_info*object
rendition_corrected_info*object
raw_photo_hash*string
image_photo_hash*string
image_thumbnail_url*string
name*string
request_idstring
pipeline_buildstring
tagsobject[]
comment_countinteger
account_id*string(uuid)
updated_at*string(date-time)
created_at*string(date-time)
security_scorenumber
attestation_validatedboolean
device_fingerprint_idstring
camera_fingerprint_idstring
sequence_numberinteger
integrity_scorenumber
jailbreak_indicatorsstring[]
capture_gps_latitudenumber
capture_gps_longitudenumber
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "psd_export": null,
  "anchored_in": null,
  "status": "pending",
  "failure_reason": null,
  "results": [
    {
      "verificator_id": "550e8400-e29b-41d4-a716-446655440000",
      "verification_id": "550e8400-e29b-41d4-a716-446655440000",
      "details": {},
      "result": null,
      "confidence_score": 0,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "result": null,
  "result_confidence": null,
  "assurance_level": null,
  "assurance_reason": null,
  "verdict": null,
  "verdict_reason": null,
  "evidence_report": null,
  "verification_mode": "raw_pair",
  "capture_verified": false,
  "raw_metadata": null,
  "image_metadata": null,
  "rendition_info": null,
  "rendition_corrected_info": null,
  "raw_photo_hash": null,
  "image_photo_hash": null,
  "image_thumbnail_url": null,
  "name": null,
  "request_id": null,
  "pipeline_build": null,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": null
    }
  ],
  "comment_count": 0,
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "security_score": null,
  "attestation_validated": false,
  "device_fingerprint_id": null,
  "camera_fingerprint_id": null,
  "sequence_number": null,
  "integrity_score": null,
  "jailbreak_indicators": null,
  "capture_gps_latitude": null,
  "capture_gps_longitude": null
}
▶ Error Responses (2)
404Verification not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE/v1/verifications/{verification_id}
Auth

Delete Verification

Delete a verification permanently.

▶View Details

Parameters

NameInType
verification_id*pathstring

✓ Response 200 — Verification deleted

FieldType
detail*string
▶ Example Response
{
  "detail": "string"
}
▶ Error Responses (3)
403Access denied
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/share
Auth

Get Verification Share

Get current sharing configuration for a verification.

▶View Details

Parameters

NameInType
verification_id*pathstring

✓ Response 200 — Share settings returned

FieldType
verification_id*string(uuid)
access_type*"restricted" | "anyone_with_link"
share_url*string
invited_emails*string[]
▶ Example Response
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_type": "restricted",
  "share_url": "string",
  "invited_emails": [
    "string"
  ]
}
▶ Error Responses (3)
403Sharing not available
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/verifications/{verification_id}/share
Auth

Create Or Update Verification Share

Enable or update sharing settings for a verification.

▶View Details

Parameters

NameInType
verification_id*pathstring

Request Body (application/json) *

FieldType
access_type*"restricted" | "anyone_with_link"
▶ Example Request
{
  "access_type": "anyone_with_link"
}

✓ Response 200 — Sharing enabled or updated

FieldType
verification_id*string(uuid)
access_type*"restricted" | "anyone_with_link"
share_url*string
invited_emails*string[]
▶ Example Response
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_type": "restricted",
  "share_url": "string",
  "invited_emails": [
    "string"
  ]
}
▶ Error Responses (3)
403Sharing not available
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE/v1/verifications/{verification_id}/share
Auth

Delete Verification Share

Disable sharing for a verification (make it private).

▶View Details

Parameters

NameInType
verification_id*pathstring

✓ Response 200 — Sharing disabled

FieldType
detail*string
▶ Example Response
{
  "detail": "string"
}
▶ Error Responses (3)
403Sharing not available
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/verifications/{verification_id}/share/invites
Auth

Add Verification Invite

Invite a specific user to access a shared verification.

▶View Details

Parameters

NameInType
verification_id*pathstring

Request Body (application/json) *

FieldType
email*string(email)
▶ Example Request
{
  "email": "editor@newspaper.com"
}

✓ Response 200 — User invited

FieldType
email*string
user_exists*boolean
▶ Example Response
{
  "email": "string",
  "user_exists": true
}
▶ Error Responses (4)
400Not shared
403Sharing not available
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE/v1/verifications/{verification_id}/share/invites
Auth

Remove Verification Invite

Remove a user's access to a shared verification.

▶View Details

Parameters

NameInType
verification_id*pathstring

Request Body (application/json) *

FieldType
email*string(email)
▶ Example Request
{
  "email": "editor@newspaper.com"
}

✓ Response 200 — User access revoked

FieldType
detail*string
▶ Example Response
{
  "detail": "string"
}
▶ Error Responses (3)
403Sharing not available
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/analytics/views
Auth

Get Verification View Analytics

Get view analytics for a shared verification.

▶View Details

Parameters

NameInType
verification_id*pathstring
start_datequerystring
end_datequerystring

✓ Response 200 — View analytics returned

FieldType
total_views*integer
daily_views*object[]
▶ Example Response
{
  "total_views": 0,
  "daily_views": [
    {
      "date": "string",
      "count": 0
    }
  ]
}
▶ Error Responses (3)
400Invalid date format
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/renditions/thumbnail
Auth

Get Verification Thumbnail

Get the thumbnail image for a verification.

▶View Details

Parameters

NameInType
verification_id*pathstring
▶ Example Response
null

302: Redirect to CDN thumbnail URL

▶ Error Responses (2)
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/renditions/signed/original
Auth

Get Verification Watermarked Image

Download the original JPEG with the Lumethic badge strip (the "asset tag" rendition).

▶View Details

Parameters

NameInType
verification_id*pathstring

302: Redirect to pre-signed S3 URL for the watermarked image

307: Redirect to watermarked image URL with verification strip.

▶ Error Responses (2)
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/psd-export
Auth

Poll a PSD export's state

Poll one PSD export's state.

▶View Details

Parameters

NameInType
verification_id*pathstring

✓ Response 200 — Successful Response

FieldType
status*"pending" | "queued" | "in_progress" | "completed" | "failed"
file_size_bytesinteger
canvas_widthinteger
canvas_heightinteger
downloads_usedinteger
downloads_limitinteger
expires_atstring
errorstring
created_at*string(date-time)
▶ Example Response
{
  "status": "pending",
  "file_size_bytes": null,
  "canvas_width": null,
  "canvas_height": null,
  "downloads_used": 0,
  "downloads_limit": 5,
  "expires_at": null,
  "error": null,
  "created_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (2)
404Verification not found, or no export requested yet (PSD_EXPORT_NOT_FOUND)
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/verifications/{verification_id}/psd-export
Auth

Request a flicker-comparison PSD export

Request a layered PSD of a completed RAW+JPEG verification.

▶View Details

Parameters

NameInType
verification_id*pathstring
waitqueryinteger

✓ Response 202 — Export state (existing or newly created)

FieldType
status*"pending" | "queued" | "in_progress" | "completed" | "failed"
file_size_bytesinteger
canvas_widthinteger
canvas_heightinteger
downloads_usedinteger
downloads_limitinteger
expires_atstring
errorstring
created_at*string(date-time)
▶ Example Response
{
  "status": "pending",
  "file_size_bytes": null,
  "canvas_width": null,
  "canvas_height": null,
  "downloads_used": 0,
  "downloads_limit": 5,
  "expires_at": null,
  "error": null,
  "created_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (5)
402Budget cap would be exceeded (BUDGET_EXCEEDED)
403Plan not entitled — Professional+ only (NOT_ENTITLED)
404Verification not found
409Verification not completed, or image-only (VALIDATION_ERROR)
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/psd-export/download
Auth

Download the generated PSD

Redirect to a short-lived signed URL for the generated PSD.

▶View Details

Parameters

NameInType
verification_id*pathstring

302: Redirect to a short-lived signed URL; consumes one of the 5 downloads

307: Successful Response

▶ Error Responses (5)
403Download limit used up (DOWNLOAD_LIMIT_REACHED)
404Verification not found, or no export requested yet (PSD_EXPORT_NOT_FOUND)
409Export not ready yet
410Export expired — re-request to regenerate free of charge (EXPIRED)
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/image
Auth

Get Verification Image

Download the JPEG image file for a verification.

▶View Details

Parameters

NameInType
verification_id*pathstring

302: Redirect to pre-signed S3 URL for direct download

307: Redirects to a temporary direct download URL for the JPEG image.

▶ Error Responses (2)
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/verifications/{verification_id}/tags
Auth

Add tags to a verification

Add tags without touching the ones already present (safe for concurrent scripts).

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)

Request Body (application/json) *

FieldType
tags*string[]
▶ Example Request
{
  "tags": [
    "Client A",
    "wedding",
    "invoice sent"
  ]
}

✓ Response 200 — Successful Response

FieldType
tags*object[]
▶ Example Response
{
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": null
    }
  ]
}
▶ Error Responses (2)
404Verification not found
422Invalid tag name, or too many tags
PUT/v1/verifications/{verification_id}/tags
Auth

Replace the tags on a verification

Set the verification's tags to exactly this list.

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)

Request Body (application/json) *

FieldType
tags*string[]
▶ Example Request
{
  "tags": [
    "Client A",
    "wedding",
    "invoice sent"
  ]
}

✓ Response 200 — Successful Response

FieldType
tags*object[]
▶ Example Response
{
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": null
    }
  ]
}
▶ Error Responses (2)
404Verification not found
422Invalid tag name, or too many tags
DELETE/v1/verifications/{verification_id}/tags/{tag_id}
Auth

Remove one tag from a verification

Detach a tag from the verification. The tag stays in the account vocabulary.

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)
tag_id*pathstring(uuid)

✓ Response 200 — Successful Response

FieldType
tags*object[]
▶ Example Response
{
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": null
    }
  ]
}
▶ Error Responses (2)
404Verification not found, or tag not on this verification
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
GET/v1/verifications/{verification_id}/comments
Auth

List comments on a verification

All comments on the verification, oldest first. Visible to the owning account only.

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)

✓ Response 200 — Successful Response

FieldType
items*object[]
total*integer
▶ Example Response
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "verification_id": "550e8400-e29b-41d4-a716-446655440000",
      "author_user_id": null,
      "author_name": null,
      "body": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "edited_at": null
    }
  ],
  "total": 0
}
▶ Error Responses (2)
404Verification not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/verifications/{verification_id}/comments
Auth

Add a comment to a verification

Post an internal comment. The author is the calling user; API-key calls carry the key's owner.

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)

Request Body (application/json) *

FieldType
body*string
▶ Example Request
{
  "body": "Client confirmed this is the final edit."
}

✓ Response 201 — Successful Response

FieldType
id*string(uuid)
verification_id*string(uuid)
author_user_id*string
author_name*string
body*string
created_at*string(date-time)
updated_at*string(date-time)
edited_atstring
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "author_user_id": null,
  "author_name": null,
  "body": "string",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "edited_at": null
}
▶ Error Responses (2)
404Verification not found
422Empty or oversized comment, or comment limit reached
DELETE/v1/verifications/{verification_id}/comments/{comment_id}
Auth

Delete a comment

Delete a comment. Allowed for its author and for admins of the account.

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)
comment_id*pathstring(uuid)

204: Successful Response

▶ Error Responses (3)
403Not the author and not an account admin
404Comment not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
PATCH/v1/verifications/{verification_id}/comments/{comment_id}
Auth

Edit your own comment

Replace the body of a comment you wrote. Stamps ``edited_at``.

▶View Details

Parameters

NameInType
verification_id*pathstring(uuid)
comment_id*pathstring(uuid)

Request Body (application/json) *

FieldType
body*string
▶ Example Request
{
  "body": "Client confirmed this is the final edit (v2)."
}

✓ Response 200 — Successful Response

FieldType
id*string(uuid)
verification_id*string(uuid)
author_user_id*string
author_name*string
body*string
created_at*string(date-time)
updated_at*string(date-time)
edited_atstring
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "author_user_id": null,
  "author_name": null,
  "body": "string",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "edited_at": null
}
▶ Error Responses (3)
403Not the comment's author
404Comment not found
422Empty or oversized comment

Public Access

Public endpoints without authentication. Perfect for anonymous verifications and accessing shared results.

1 endpoint
GET/v1/public/health
Public

Health Check

Check API health status for monitoring and integration verification.

▶View Details
▶ Example Response
{}
▶ Error Responses (1)
404Not found

API Keys

Programmatically manage API keys for your account.

3 endpoints
GET/v1/apikeys/
Auth

List Api Keys

List all API keys for your current account.

▶View Details
▶ Example Response
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prefix": "string",
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "description": null,
    "expires_at": "2024-01-15T10:30:00Z",
    "is_active": true,
    "last_used_at": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
▶ Error Responses (1)
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/apikeys/
Auth

Create Api Key

Create a new API key for programmatic access to the Lumethic API.

▶View Details

Request Body (application/json) *

FieldType
descriptionstring
account_id*string(uuid)
expires_in_daysinteger
scopestring
▶ Example Request
{
  "account_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "description": "CI/CD pipeline key",
  "expires_in_days": 90
}

✓ Response 201 — API key created successfully

FieldType
id*string(uuid)
prefix*string
account_id*string(uuid)
user_id*string(uuid)
description*string
expires_at*string(date-time)
created_at*string(date-time)
raw_key*string
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prefix": "string",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": null,
  "expires_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "raw_key": "string"
}
▶ Error Responses (2)
403Access denied
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE/v1/apikeys/{key_id}
Auth

Revoke Api Key

Revoke an API key, permanently disabling it.

▶View Details

Parameters

NameInType
key_id*pathstring(uuid)

204: Key revoked successfully

▶ Error Responses (2)
404API key not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Other

9 endpoints
GET/v1/tags/
Auth

List the account's tags

List every tag of the account with the number of verifications carrying it, sorted by name.

▶View Details

✓ Response 200 — Successful Response

FieldType
items*object[]
▶ Example Response
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": null,
      "verification_count": 0,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}
▶ Error Responses (2)
404Not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/tags/
Auth

Create a tag

Create a tag in the account vocabulary. Names are unique per account, case-insensitively.

▶View Details

Request Body (application/json) *

FieldType
name*string
colorstring
▶ Example Request
{
  "color": "#1a73e8",
  "name": "Client A"
}

✓ Response 201 — Successful Response

FieldType
id*string(uuid)
name*string
colorstring
verification_countinteger
created_at*string(date-time)
updated_at*string(date-time)
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "color": null,
  "verification_count": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (3)
404Not found
409Tag already exists
422Invalid name or colour
DELETE/v1/tags/{tag_id}
Auth

Delete a tag

Delete a tag from the vocabulary and detach it from every verification. Verifications are untouched.

▶View Details

Parameters

NameInType
tag_id*pathstring(uuid)

204: Successful Response

▶ Error Responses (2)
404Tag not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
PATCH/v1/tags/{tag_id}
Auth

Rename or recolour a tag

Update a tag's name and/or colour. A rename is reflected on every verification carrying it.

▶View Details

Parameters

NameInType
tag_id*pathstring(uuid)

Request Body (application/json) *

FieldType
namestring
colorstring
▶ Example Request
{
  "name": "Client B"
}

✓ Response 200 — Successful Response

FieldType
id*string(uuid)
name*string
colorstring
verification_countinteger
created_at*string(date-time)
updated_at*string(date-time)
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "color": null,
  "verification_count": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (3)
404Tag not found
409Tag already exists
422Invalid name or colour
GET/v1/requests
Auth

List the account's verification requests

List requests newest first, optionally filtered by derived status.

▶View Details

Parameters

NameInType
offsetqueryinteger
sizequeryinteger
statusquery"open" | "closed" | "expired"

✓ Response 200 — Successful Response

FieldType
items*object[]
total*integer
offset*integer
size*integer
total_pages*integer
▶ Example Response
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "subject": "string",
      "instructions": null,
      "mode": "...",
      "status": "...",
      "expires_at": "2024-01-15T10:30:00Z",
      "closed_at": null,
      "max_submissions": 0,
      "submission_count": 0,
      "share_with_provider": true,
      "token": "string",
      "url": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 0,
  "offset": 0,
  "size": 0,
  "total_pages": 0
}
▶ Error Responses (1)
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
POST/v1/requests
Auth

Create a verification request

Create a request and return its link.

▶View Details

Request Body (application/json) *

FieldType
subject*string
instructionsstring
expires_at*string(date-time)
max_submissionsinteger
share_with_providerboolean
mode"existing_original" | "capture"
▶ Example Request
{
  "subject": "string",
  "instructions": null,
  "expires_at": "2024-01-15T10:30:00Z",
  "max_submissions": null,
  "share_with_provider": true,
  "mode": "existing_original"
}

✓ Response 201 — Successful Response

FieldType
id*string(uuid)
subject*string
instructions*string
mode*"existing_original" | "capture"
status*"open" | "closed" | "expired"
expires_at*string(date-time)
closed_at*string
max_submissions*integer
submission_count*integer
share_with_provider*boolean
token*string
url*string
created_at*string(date-time)
updated_at*string(date-time)
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "subject": "string",
  "instructions": null,
  "mode": "existing_original",
  "status": "open",
  "expires_at": "2024-01-15T10:30:00Z",
  "closed_at": null,
  "max_submissions": 0,
  "submission_count": 0,
  "share_with_provider": true,
  "token": "string",
  "url": "string",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (2)
400Account name required
422Invalid request
GET/v1/requests/{request_id}
Auth

Read a verification request

Read one request, including its token and link, so the requester page can re-show and re-print them.

▶View Details

Parameters

NameInType
request_id*pathstring(uuid)

✓ Response 200 — Successful Response

FieldType
id*string(uuid)
subject*string
instructions*string
mode*"existing_original" | "capture"
status*"open" | "closed" | "expired"
expires_at*string(date-time)
closed_at*string
max_submissions*integer
submission_count*integer
share_with_provider*boolean
token*string
url*string
created_at*string(date-time)
updated_at*string(date-time)
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "subject": "string",
  "instructions": null,
  "mode": "existing_original",
  "status": "open",
  "expires_at": "2024-01-15T10:30:00Z",
  "closed_at": null,
  "max_submissions": 0,
  "submission_count": 0,
  "share_with_provider": true,
  "token": "string",
  "url": "string",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (2)
404Request not found
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
DELETE/v1/requests/{request_id}
Auth

Delete a verification request that has no submissions

Delete a request while it has no submissions. Once it has any, close it; deleting would detach records.

▶View Details

Parameters

NameInType
request_id*pathstring(uuid)

204: Successful Response

▶ Error Responses (3)
404Request not found
409Request has submissions
422Validation Error
{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
PATCH/v1/requests/{request_id}
Auth

Close or edit a verification request

Close a request (terminal) or edit its subject, instructions, expiry, cap or share default.

▶View Details

Parameters

NameInType
request_id*pathstring(uuid)

Request Body (application/json) *

FieldType
statusstring
subjectstring
instructionsstring
expires_atstring
max_submissionsinteger
share_with_providerboolean
▶ Example Request
{
  "status": null,
  "subject": null,
  "instructions": null,
  "expires_at": null,
  "max_submissions": null,
  "share_with_provider": null
}

✓ Response 200 — Successful Response

FieldType
id*string(uuid)
subject*string
instructions*string
mode*"existing_original" | "capture"
status*"open" | "closed" | "expired"
expires_at*string(date-time)
closed_at*string
max_submissions*integer
submission_count*integer
share_with_provider*boolean
token*string
url*string
created_at*string(date-time)
updated_at*string(date-time)
▶ Example Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "subject": "string",
  "instructions": null,
  "mode": "existing_original",
  "status": "open",
  "expires_at": "2024-01-15T10:30:00Z",
  "closed_at": null,
  "max_submissions": 0,
  "submission_count": 0,
  "share_with_provider": true,
  "token": "string",
  "url": "string",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
▶ Error Responses (2)
404Request not found
422Invalid update

Response Codes

200 Success · 201 Created · 204 Deleted

302/307 Redirect

400 Bad request · 401 Unauthorized · 402 Quota exceeded

403 Forbidden · 404 Not found · 422 Validation error

429 Rate limit exceeded

OpenAPI Specification

Download the complete spec for code generation and API clients.