The Lumethic Verification API

A photo verification API takes an uploaded image, checks it against its camera RAW file or its Content Credentials, and returns a signed result your application can act on. The Lumethic REST API does that for user-uploaded photos at any volume.

What the API does

You send a photo and, when you have it, the RAW file it came from. The API checks that the RAW holds real sensor data, that the photo matches it and that the metadata of both agrees with the camera, then attaches a Lumethic-attested C2PA credential that records the result. Without a RAW it checks the Content Credentials the file already carries. The RAW is used for that check only, and processing runs in the European Union.

Three endpoints cover the workflow: POST /v1/verifications/ uploads the files and starts the check, GET /v1/verifications/{id} returns the status and the result, and POST /v1/verifications/{id}/share creates a report link you can hand to a reviewer. The full reference below lists every endpoint with request and response examples, and the same key works for the MCP server.

Pricing is per verification. The free plan includes 5 verifications a month, Basic includes 25 for €3.95 a month, Professional includes 500 for €49.95 a month, and additional verifications cost €0.25 each. Checks of an image without a RAW file are free and do not count toward the quota. Enterprise volumes are priced on request.

How to Get Started

Sign Up

Create an account to get access to the API.

Get Your Key

Generate an API key from your account dashboard.

Start Building

Use the documentation below to integrate and start verifying.

Using Lumethic from AI agents

Prefer to call Lumethic from an AI agent instead of raw HTTP? Our Model Context Protocol (MCP) server lets any MCP-capable client verify photo authenticity over a Streamable HTTP endpoint — with the same API key.

https://api.lumethic.com/mcp

View MCP docs

Sign Up to Get Started

Authenticate your requests by passing your API key as a Bearer Token in the Authorization header. You can create and manage your keys in your account dashboard.

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

Name	In	Type	Description
offset	query	integer	Number of items to skip for pagination
size	query	integer	Number of items to return per page (max 100)
sort_by	query	string	Field to sort by: 'status', 'created_at', or 'updated_at'
sort_order	query	string	Sort order: 'asc' for ascending or 'desc' for descending
search	query	string	Search by verification name, ID, or photo hash
status	query	string	Filter by verification status. Supports comma-separated values: 'pending', 'queued', 'in_progress', 'completed', or 'failed'. Example: 'pending,queued,in_progress'
result	query	string	Filter by authenticity result: 'true' for authentic images, 'false' for non-authentic
tags	query	string	Filter by tag names, comma-separated and case-insensitive (max 10). By default every listed tag must be on the verification; see tag_match. Example: 'client a,wedding'
tag_match	query	string	How multiple tags combine: 'all' (default, every tag must match) or 'any' (at least one)
request_id	query	string	Only the records that answered this verification request (REQUEST_PATH_PLAN.md §3.4)

✓ Response 200 — Paginated list of verifications

Field	Type	Description
items*	object[]	Array of verification objects
total*	integer	Total number of verifications matching the query
offset*	integer	Current offset position in the result set
size*	integer	Number of items returned in this page
total_pages*	integer	Total number of pages available

▶ 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) *

Field	Type	Description
image*	string(binary)	Image file (JPEG, PNG, WebP, HEIF/HEIC, AVIF, TIFF, GIF). For a RAW+image pair, embedded camera EXIF adds a corroborating metadata cross-check when present, but it is advisory — an EXIF-less image (PNG/WebP/… or a stripped JPEG) still verifies on RAW authenticity + pixel correspondence. Omit `raw` for an image-only C2PA verification.
raw	string	Optional RAW file (.cr2, .nef, .arw, .dng, …). Omit for image-only C2PA verification.
attestation_id	string	Pre-validated attestation ID from POST /capture/attestation

▶ Example Request

{
  "image": "<binary file>",
  "raw": null,
  "attestation_id": null
}

✓ Response 201 — Verification created and queued for processing

Field	Type	Description
id*	string(uuid)	Unique identifier for the created verification
security_score	number	Device security score from 0.0 to 1.0 if attestation was provided. Higher values indicate more trustworthy device integrity.

▶ 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) *

Field	Type	Description
anonymous_user_id*	string	The anonymous user ID whose verifications should be claimed

▶ Example Request

{
  "anonymous_user_id": "string"
}

✓ Response 200 — Anonymous verifications claimed

Field	Type	Description
claimed*	integer	Number of verifications transferred into the account
verification_ids*	string[]	IDs of the verifications that were claimed

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

✓ Response 200 — Verification details returned

Field	Type	Description
id*	string(uuid)	Unique identifier for the verification
psd_export	object	PSD flicker-export state (PSD_EXPORT_PLAN.md P4): whether the account can request one for this verification, and the current export's status when one exists.
anchored_in	object[]	Offloads whose anchored hash lists contain this verification's RAW file (ACQUISITION_MANIFEST_PLAN.md §4). anchored_at is attested by the timestamp authority; it is distinct from and earlier than verification time.
status*	"pending" \| "queued" \| "in_progress" \| "completed" \| "failed"	Current processing status of the verification
failure_reason	string	Why a `failed` verification failed, in client terms: `sandbox_rejected` (the RAW sandbox rejected the file; its message is in `raw_metadata.raw_validation_error`), `attempts_exhausted` (every processing attempt died the same way, e.g. timed out on a very large RAW; a plain retry will not help) or `processing_error` (ours; worth a retry). Null unless status is `failed`. Decoder refusals do not fail: they complete as `unrated_unsupported_format` with the variant named.
results*	object[]	Array of detailed results from each verification algorithm
result*	boolean	Overall authenticity determination: true = authentic, false = not authentic, null = pending
result_confidence*	number	Legacy 0.0-1.0 score. NOT a probability of authenticity: for pair verifications it is the plain mean of the six non-informational checks (RAW_AUTHENTICITY, RECAPTURE, SSIM, IMAGEHASH, HISTOGRAM, FACES; EXIF, C2PA and image forensics are excluded). SSIM, IMAGEHASH and HISTOGRAM measure how closely the JPEG matches a neutral render of the RAW, so cropping, grading and resizing lower it; FACES contributes a fixed 0.8 when neither file has a face and RECAPTURE a fixed 0.9 when clean, so an unedited camera JPEG scores about 0.95. An abstaining check contributes 0.0. For image-only verifications it is the C2PA check's own confidence. Key on assurance_level; do not present this value as a percentage of certainty.
assurance_level	"verified" \| "provisional" \| "provenance" \| "unrated" \| "flagged"	Graded assurance level: verified/provisional (capture verified) \| provenance (C2PA only) \| unrated \| flagged. Prefer this and capture_verified over the legacy `result` boolean.
assurance_reason	string	Qualifier for the level, e.g. 'unrated_no_evidence' or 'unrated_unsupported_format'
verdict	"ai_declared" \| "modified_after_signing" \| "provenance_verified" \| "self_declared_ai" \| "unrated"	Evidence-report verdict category (image-only). Additive: assurance_level is derived from it by a fixed mapping, so the two can never contradict.
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"	Machine-readable refinement of the verdict, e.g. 'c2pa_trusted_capture'
evidence_report	object	Full evidence report (findings, coverage, boundaries) for completed image-only verifications
verification_mode	"raw_pair" \| "image_only"	Inputs used: raw_pair or image_only
capture_verified	boolean	True only when optical capture was forensically verified (verified/provisional). Integrators should treat this as the authoritative 'passed' signal.
raw_metadata*	object	EXIF and technical metadata from the RAW file
image_metadata*	object	EXIF and technical metadata from the JPEG file
rendition_info*	object	Transformation details between RAW and JPEG
rendition_corrected_info*	object	Lens-corrected transformation details between RAW and JPEG
raw_photo_hash*	string	SHA-256 hash of the RAW file for integrity verification
image_photo_hash*	string	SHA-256 hash of the JPEG file for integrity verification
image_thumbnail_url*	string	CDN URL for the verification thumbnail image
name*	string	User-provided name or original filename
request_id	string	The verification request this record answers, when it came in through a request link
pipeline_build	string	CI image tag of the pipeline that produced the result; a build identifier
tags	object[]	Account tags on this verification (owner-only; never on public responses)
comment_count	integer	Number of internal comments on this verification
account_id*	string(uuid)	Account that owns this verification
updated_at*	string(date-time)	ISO 8601 timestamp of last update
created_at*	string(date-time)	ISO 8601 timestamp when verification was created
security_score	number	Device security score from 0.0 to 1.0 if attestation was provided. Higher = more trustworthy.
attestation_validated	boolean	Whether device attestation was provided and validated
device_fingerprint_id	string	Unique identifier for the device that captured the photo
camera_fingerprint_id	string	Unique identifier for the camera hardware used
sequence_number	integer	Sequential capture number from the app session for tamper detection
integrity_score	number	App integrity score from attestation (0.0 to 1.0)
jailbreak_indicators	string[]	List of detected jailbreak/root indicators on the device
capture_gps_latitude	number	GPS latitude at time of capture
capture_gps_longitude	number	GPS longitude at time of capture

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

✓ Response 200 — Verification deleted

Field	Type	Description
detail*	string	Human-readable message describing the result of the operation

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

✓ Response 200 — Share settings returned

Field	Type	Description
verification_id*	string(uuid)	The verification being shared
access_type*	"restricted" \| "anyone_with_link"	Who can access this shared verification
share_url*	string	Public URL to view the shared verification
invited_emails*	string[]	Email addresses with access (for restricted sharing)

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

Request Body (application/json) *

Field	Type	Description
access_type*	"restricted" \| "anyone_with_link"	—

▶ Example Request

{
  "access_type": "anyone_with_link"
}

✓ Response 200 — Sharing enabled or updated

Field	Type	Description
verification_id*	string(uuid)	The verification being shared
access_type*	"restricted" \| "anyone_with_link"	Who can access this shared verification
share_url*	string	Public URL to view the shared verification
invited_emails*	string[]	Email addresses with access (for restricted sharing)

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

✓ Response 200 — Sharing disabled

Field	Type	Description
detail*	string	Human-readable message describing the result of the operation

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

Request Body (application/json) *

Field	Type	Description
email*	string(email)	Email

▶ Example Request

{
  "email": "editor@newspaper.com"
}

✓ Response 200 — User invited

Field	Type	Description
email*	string	The email address that was invited
user_exists*	boolean	Whether this email belongs to a registered Lumethic user

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

Request Body (application/json) *

Field	Type	Description
email*	string(email)	Email

▶ Example Request

{
  "email": "editor@newspaper.com"
}

✓ Response 200 — User access revoked

Field	Type	Description
detail*	string	Human-readable message describing the result of the operation

▶ 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

Name	In	Type	Description
verification_id*	path	string	—
start_date	query	string	Start date for analytics (ISO 8601 format, e.g., 2024-01-01)
end_date	query	string	End date for analytics (ISO 8601 format, e.g., 2024-12-31)

✓ Response 200 — View analytics returned

Field	Type	Description
total_views*	integer	Total number of views in the specified period
daily_views*	object[]	Daily breakdown of view counts for chart visualization

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

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

Name	In	Type	Description
verification_id*	path	string	—

✓ Response 200 — Successful Response

Field	Type	Description
status*	"pending" \| "queued" \| "in_progress" \| "completed" \| "failed"	—
file_size_bytes	integer	File Size Bytes
canvas_width	integer	Canvas Width
canvas_height	integer	Canvas Height
downloads_used	integer	Downloads Used
downloads_limit	integer	Downloads Limit
expires_at	string	Expires At
error	string	Error
created_at*	string(date-time)	Created At

▶ 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

Name	In	Type	Description
verification_id*	path	string	—
wait	query	integer	—

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

Field	Type	Description
status*	"pending" \| "queued" \| "in_progress" \| "completed" \| "failed"	—
file_size_bytes	integer	File Size Bytes
canvas_width	integer	Canvas Width
canvas_height	integer	Canvas Height
downloads_used	integer	Downloads Used
downloads_limit	integer	Downloads Limit
expires_at	string	Expires At
error	string	Error
created_at*	string(date-time)	Created At

▶ 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

Name	In	Type	Description
verification_id*	path	string	—

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

Name	In	Type	Description
verification_id*	path	string	—

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

Name	In	Type	Description
verification_id*	path	string(uuid)	—

Request Body (application/json) *

Field	Type	Description
tags*	string[]	Tag names; unknown names are created in the account vocabulary. Max 20 per verification.

▶ Example Request

{
  "tags": [
    "Client A",
    "wedding",
    "invoice sent"
  ]
}

✓ Response 200 — Successful Response

Field	Type	Description
tags*	object[]	All tags now on the verification, sorted by name

▶ 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

Name	In	Type	Description
verification_id*	path	string(uuid)	—

Request Body (application/json) *

Field	Type	Description
tags*	string[]	Tag names; unknown names are created in the account vocabulary. Max 20 per verification.

▶ Example Request

{
  "tags": [
    "Client A",
    "wedding",
    "invoice sent"
  ]
}

✓ Response 200 — Successful Response

Field	Type	Description
tags*	object[]	All tags now on the verification, sorted by name

▶ 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

Name	In	Type	Description
verification_id*	path	string(uuid)	—
tag_id*	path	string(uuid)	—

✓ Response 200 — Successful Response

Field	Type	Description
tags*	object[]	All tags now on the verification, sorted by name

▶ 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

Name	In	Type	Description
verification_id*	path	string(uuid)	—

✓ Response 200 — Successful Response

Field	Type	Description
items*	object[]	Comments, oldest first
total*	integer	Number of comments on the verification

▶ 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

Name	In	Type	Description
verification_id*	path	string(uuid)	—

Request Body (application/json) *

Field	Type	Description
body*	string	Comment text, 1-4000 characters

▶ Example Request

{
  "body": "Client confirmed this is the final edit."
}

✓ Response 201 — Successful Response

Field	Type	Description
id*	string(uuid)	Id
verification_id*	string(uuid)	Verification Id
author_user_id*	string	Null when the author's user was deleted
author_name*	string	Author's display name at read time; null when unknown
body*	string	Body
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At
edited_at	string	Set when the body was changed after posting

▶ 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

Name	In	Type	Description
verification_id*	path	string(uuid)	—
comment_id*	path	string(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

Name	In	Type	Description
verification_id*	path	string(uuid)	—
comment_id*	path	string(uuid)	—

Request Body (application/json) *

Field	Type	Description
body*	string	Replacement comment text, 1-4000 characters

▶ Example Request

{
  "body": "Client confirmed this is the final edit (v2)."
}

✓ Response 200 — Successful Response

Field	Type	Description
id*	string(uuid)	Id
verification_id*	string(uuid)	Verification Id
author_user_id*	string	Null when the author's user was deleted
author_name*	string	Author's display name at read time; null when unknown
body*	string	Body
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At
edited_at	string	Set when the body was changed after posting

▶ 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) *

Field	Type	Description
description	string	Description
account_id*	string(uuid)	Account Id
expires_in_days	integer	Expires In Days
scope	string	Scope

▶ Example Request

{
  "account_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "description": "CI/CD pipeline key",
  "expires_in_days": 90
}

✓ Response 201 — API key created successfully

Field	Type	Description
id*	string(uuid)	Unique identifier for the API key
prefix*	string	Key prefix for identification (e.g., 'ask_a1b2c3d4')
account_id*	string(uuid)	Account this key is associated with
user_id*	string(uuid)	User who created the key
description*	string	User-provided description of the key's purpose
expires_at*	string(date-time)	ISO 8601 timestamp when the key expires
created_at*	string(date-time)	ISO 8601 timestamp when the key was created
raw_key*	string	The full API key string. Store this securely — it cannot be retrieved again after creation.

▶ 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

Name	In	Type	Description
key_id*	path	string(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

Field	Type	Description
items*	object[]	The account's tags, sorted by name

▶ 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) *

Field	Type	Description
name*	string	1-40 characters, no commas; surrounding whitespace is trimmed
color	string	Optional '#rrggbb' colour

▶ Example Request

{
  "color": "#1a73e8",
  "name": "Client A"
}

✓ Response 201 — Successful Response

Field	Type	Description
id*	string(uuid)	Tag identifier
name*	string	Display name (case preserved; matching is case-insensitive)
color	string	Optional '#rrggbb' colour
verification_count	integer	Number of non-deleted verifications carrying the tag
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At

▶ 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

Name	In	Type	Description
tag_id*	path	string(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

Name	In	Type	Description
tag_id*	path	string(uuid)	—

Request Body (application/json) *

Field	Type	Description
name	string	Name
color	string	Color

▶ Example Request

{
  "name": "Client B"
}

✓ Response 200 — Successful Response

Field	Type	Description
id*	string(uuid)	Tag identifier
name*	string	Display name (case preserved; matching is case-insensitive)
color	string	Optional '#rrggbb' colour
verification_count	integer	Number of non-deleted verifications carrying the tag
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At

▶ 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

Name	In	Type	Description
offset	query	integer	—
size	query	integer	—
status	query	"open" \| "closed" \| "expired"	Filter by derived status. The three values partition the list: 'open' is stored-open and not yet past expires_at, 'expired' is stored-open past expires_at, 'closed' is stored-closed.

✓ Response 200 — Successful Response

Field	Type	Description
items*	object[]	Items
total*	integer	Total number of requests matching the filter
offset*	integer	Offset
size*	integer	Size
total_pages*	integer	Total Pages

▶ 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) *

Field	Type	Description
subject*	string	The requester's own words for what is being asked ('front of the item', 'entry 48392'). Shown on the landing page and the record, labelled as the requester's words; never something Lumethic verified. Control characters are rejected.
instructions	string	Free text for the landing page. Control characters other than newlines are rejected.
expires_at*	string(date-time)	After this instant the public routes answer 410 REQUEST_EXPIRED. Must be in the future and at most 365 days out.
max_submissions	integer	Cap on accepted uploads. Defaults by plan (free 5, paid 25) and is limited by a plan ceiling (free 5, Basic 25, Professional 250, Enterprise unlimited); above the ceiling is 422.
share_with_provider	boolean	Create the public share for every submission at upload, so the provider reaches the record.
mode	"existing_original" \| "capture"	'existing_original' takes an uploaded camera original. 'capture' takes a photograph made with Lumethic Capture: the app mints its challenge and validates its attestation with the request token in the X-Lumethic-Request-Token header, and the upload must carry that attestation_id (iOS only today).

▶ 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

Field	Type	Description
id*	string(uuid)	Id
subject*	string	Subject
instructions*	string	Instructions
mode*	"existing_original" \| "capture"	—
status*	"open" \| "closed" \| "expired"	Derived: 'expired' is 'open' past expires_at.
expires_at*	string(date-time)	Expires At
closed_at*	string	Closed At
max_submissions*	integer	Max Submissions
submission_count*	integer	Accepted uploads so far (counted, never stored).
share_with_provider*	boolean	Share With Provider
token*	string	Bearer secret: anyone holding it can open the landing page and upload to this request until it closes, expires or fills. Returned on every owner read; listing requests exposes every open link of the account.
url*	string	The landing page link (and the QR code's content): {FRONTEND_URL}/r/{token}.
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At

▶ 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

Name	In	Type	Description
request_id*	path	string(uuid)	—

✓ Response 200 — Successful Response

Field	Type	Description
id*	string(uuid)	Id
subject*	string	Subject
instructions*	string	Instructions
mode*	"existing_original" \| "capture"	—
status*	"open" \| "closed" \| "expired"	Derived: 'expired' is 'open' past expires_at.
expires_at*	string(date-time)	Expires At
closed_at*	string	Closed At
max_submissions*	integer	Max Submissions
submission_count*	integer	Accepted uploads so far (counted, never stored).
share_with_provider*	boolean	Share With Provider
token*	string	Bearer secret: anyone holding it can open the landing page and upload to this request until it closes, expires or fills. Returned on every owner read; listing requests exposes every open link of the account.
url*	string	The landing page link (and the QR code's content): {FRONTEND_URL}/r/{token}.
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At

▶ 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

Name	In	Type	Description
request_id*	path	string(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

Name	In	Type	Description
request_id*	path	string(uuid)	—

Request Body (application/json) *

Field	Type	Description
status	string	The only transition: 'closed' is terminal and cannot be reopened.
subject	string	Subject
instructions	string	Instructions
expires_at	string	Expires At
max_submissions	integer	Max Submissions
share_with_provider	boolean	Share With Provider

▶ Example Request

{
  "status": null,
  "subject": null,
  "instructions": null,
  "expires_at": null,
  "max_submissions": null,
  "share_with_provider": null
}

✓ Response 200 — Successful Response

Field	Type	Description
id*	string(uuid)	Id
subject*	string	Subject
instructions*	string	Instructions
mode*	"existing_original" \| "capture"	—
status*	"open" \| "closed" \| "expired"	Derived: 'expired' is 'open' past expires_at.
expires_at*	string(date-time)	Expires At
closed_at*	string	Closed At
max_submissions*	integer	Max Submissions
submission_count*	integer	Accepted uploads so far (counted, never stored).
share_with_provider*	boolean	Share With Provider
token*	string	Bearer secret: anyone holding it can open the landing page and upload to this request until it closes, expires or fills. Returned on every owner read; listing requests exposes every open link of the account.
url*	string	The landing page link (and the QR code's content): {FRONTEND_URL}/r/{token}.
created_at*	string(date-time)	Created At
updated_at*	string(date-time)	Updated At

▶ 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.

Download View JSON