Die Verifizierungs-API von Lumethic

Greifen Sie programmatisch auf die Foto-Verifizierungs-Engine von Lumethic zu. Automatisieren Sie Echtheitsprüfungen direkt in Ihrer Anwendung.

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 · 29 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: 50/mo, €3.95

Professional: 1,000/mo, €49.95

Enterprise: volume pricing, SLA

Overage: €0.25 (negotiable at volume). 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.

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 29 endpoints, grouped by functionality.

Verifications

Create and manage photo authenticity verifications.

14 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

✓ 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,
      "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
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
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	Confidence score from 0.0 to 1.0 for the overall result
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
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",
  "anchored_in": null,
  "status": "pending",
  "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,
  "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 Lumethic verification watermark.

▶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}/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"
    }
  ]
}

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., 'lk_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"
    }
  ]
}

Marketplace

Buy and sell verified authentic photos with built-in licensing.

11 endpoints

GET/v1/marketplace/listings

Auth

Get Seller Listings

List all marketplace listings owned by your account.

▶View Details

Parameters

Name	In	Type	Description
limit	query	integer	Maximum number of results to return
offset	query	integer	Number of results to skip for pagination

▶ Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "string",
    "description": null,
    "is_active": true,
    "currency": "string",
    "price_personal_cents": null,
    "price_commercial_cents": null,
    "price_editorial_cents": null,
    "price_extended_cents": null,
    "license_terms_personal": null,
    "license_terms_commercial": null,
    "license_terms_editorial": null,
    "license_terms_extended": null,
    "total_sales": 0,
    "total_revenue_cents": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]

▶ Error Responses (2)

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

POST/v1/marketplace/listings

Auth

Create Listing

Create a marketplace listing for a verified photo.

▶View Details

Parameters

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

Request Body (application/json) *

Field	Type	Description
title*	string	Title
description	string	Description
currency	"usd" \| "cad" \| "mxn" \| "eur" \| "gbp" \| "chf" \| "sek" \| "nok" \| "dkk" \| "pln" \| "czk" \| "huf" \| "ron" \| "bgn" \| "aud" \| "nzd" \| "jpy" \| "sgd" \| "hkd" \| "krw" \| "cny" \| "inr" \| "thb" \| "myr" \| "brl" \| "aed" \| "zar" \| "ils"	—
price_personal_cents	integer	Price Personal Cents
price_commercial_cents	integer	Price Commercial Cents
price_editorial_cents	integer	Price Editorial Cents
price_extended_cents	integer	Price Extended Cents
license_terms_personal	string	License Terms Personal
license_terms_commercial	string	License Terms Commercial
license_terms_editorial	string	License Terms Editorial
license_terms_extended	string	License Terms Extended

▶ Example Request

{
  "currency": "usd",
  "description": "Authenticated landscape photo taken with Nikon Z9",
  "license_terms_commercial": "Commercial use in marketing materials",
  "license_terms_editorial": "Editorial use in news and publications",
  "license_terms_extended": "Unlimited commercial use including merchandise",
  "license_terms_personal": "Personal use only, no redistribution",
  "price_commercial_cents": 5000,
  "price_editorial_cents": 2000,
  "price_extended_cents": 10000,
  "price_personal_cents": 1000,
  "title": "Sunset over Lake Zurich"
}

✓ Response 201 — Listing created successfully

Field	Type	Description
id*	string(uuid)	Unique identifier for the listing
verification_id*	string(uuid)	ID of the verified photo this listing represents
title*	string	Display title for the listing
description*	string	Optional description of the photo and its context
is_active*	boolean	Whether the listing is currently available for purchase
currency*	string	ISO 4217 currency code (e.g., 'usd', 'eur', 'chf')
price_personal_cents*	integer	Price in cents for personal use license
price_commercial_cents*	integer	Price in cents for commercial use license
price_editorial_cents*	integer	Price in cents for editorial use license
price_extended_cents*	integer	Price in cents for extended/unlimited use license
license_terms_personal*	string	Terms and restrictions for personal use
license_terms_commercial*	string	Terms and restrictions for commercial use
license_terms_editorial*	string	Terms and restrictions for editorial use
license_terms_extended*	string	Terms and restrictions for extended use
total_sales*	integer	Total number of licenses sold for this listing
total_revenue_cents*	integer	Total revenue generated in cents
created_at*	string	ISO 8601 timestamp when the listing was created
updated_at*	string	ISO 8601 timestamp when the listing was last modified

▶ Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "string",
  "description": null,
  "is_active": true,
  "currency": "string",
  "price_personal_cents": null,
  "price_commercial_cents": null,
  "price_editorial_cents": null,
  "price_extended_cents": null,
  "license_terms_personal": null,
  "license_terms_commercial": null,
  "license_terms_editorial": null,
  "license_terms_extended": null,
  "total_sales": 0,
  "total_revenue_cents": 0,
  "created_at": "string",
  "updated_at": "string"
}

▶ Error Responses (4)

402Plan upgrade required

403Anonymous verification

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

GET/v1/marketplace/listings/{listing_id}

Public

Get Listing

Get a marketplace listing by ID.

▶View Details

Parameters

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

✓ Response 200 — Listing returned

Field	Type	Description
id*	string(uuid)	Unique identifier for the listing
verification_id*	string(uuid)	ID of the verified photo this listing represents
title*	string	Display title for the listing
description*	string	Optional description of the photo and its context
is_active*	boolean	Whether the listing is currently available for purchase
currency*	string	ISO 4217 currency code (e.g., 'usd', 'eur', 'chf')
price_personal_cents*	integer	Price in cents for personal use license
price_commercial_cents*	integer	Price in cents for commercial use license
price_editorial_cents*	integer	Price in cents for editorial use license
price_extended_cents*	integer	Price in cents for extended/unlimited use license
license_terms_personal*	string	Terms and restrictions for personal use
license_terms_commercial*	string	Terms and restrictions for commercial use
license_terms_editorial*	string	Terms and restrictions for editorial use
license_terms_extended*	string	Terms and restrictions for extended use
total_sales*	integer	Total number of licenses sold for this listing
total_revenue_cents*	integer	Total revenue generated in cents
created_at*	string	ISO 8601 timestamp when the listing was created
updated_at*	string	ISO 8601 timestamp when the listing was last modified

▶ Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "string",
  "description": null,
  "is_active": true,
  "currency": "string",
  "price_personal_cents": null,
  "price_commercial_cents": null,
  "price_editorial_cents": null,
  "price_extended_cents": null,
  "license_terms_personal": null,
  "license_terms_commercial": null,
  "license_terms_editorial": null,
  "license_terms_extended": null,
  "total_sales": 0,
  "total_revenue_cents": 0,
  "created_at": "string",
  "updated_at": "string"
}

▶ Error Responses (2)

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

PUT/v1/marketplace/listings/{listing_id}

Auth

Update Listing

Update an existing marketplace listing.

▶View Details

Parameters

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

Request Body (application/json) *

Field	Type	Description
title*	string	Title
description	string	Description
currency	"usd" \| "cad" \| "mxn" \| "eur" \| "gbp" \| "chf" \| "sek" \| "nok" \| "dkk" \| "pln" \| "czk" \| "huf" \| "ron" \| "bgn" \| "aud" \| "nzd" \| "jpy" \| "sgd" \| "hkd" \| "krw" \| "cny" \| "inr" \| "thb" \| "myr" \| "brl" \| "aed" \| "zar" \| "ils"	—
price_personal_cents	integer	Price Personal Cents
price_commercial_cents	integer	Price Commercial Cents
price_editorial_cents	integer	Price Editorial Cents
price_extended_cents	integer	Price Extended Cents
license_terms_personal	string	License Terms Personal
license_terms_commercial	string	License Terms Commercial
license_terms_editorial	string	License Terms Editorial
license_terms_extended	string	License Terms Extended

▶ Example Request

{
  "currency": "usd",
  "description": "Authenticated landscape photo taken with Nikon Z9",
  "license_terms_commercial": "Commercial use in marketing materials",
  "license_terms_editorial": "Editorial use in news and publications",
  "license_terms_extended": "Unlimited commercial use including merchandise",
  "license_terms_personal": "Personal use only, no redistribution",
  "price_commercial_cents": 5000,
  "price_editorial_cents": 2000,
  "price_extended_cents": 10000,
  "price_personal_cents": 1000,
  "title": "Sunset over Lake Zurich"
}

✓ Response 200 — Listing updated successfully

Field	Type	Description
id*	string(uuid)	Unique identifier for the listing
verification_id*	string(uuid)	ID of the verified photo this listing represents
title*	string	Display title for the listing
description*	string	Optional description of the photo and its context
is_active*	boolean	Whether the listing is currently available for purchase
currency*	string	ISO 4217 currency code (e.g., 'usd', 'eur', 'chf')
price_personal_cents*	integer	Price in cents for personal use license
price_commercial_cents*	integer	Price in cents for commercial use license
price_editorial_cents*	integer	Price in cents for editorial use license
price_extended_cents*	integer	Price in cents for extended/unlimited use license
license_terms_personal*	string	Terms and restrictions for personal use
license_terms_commercial*	string	Terms and restrictions for commercial use
license_terms_editorial*	string	Terms and restrictions for editorial use
license_terms_extended*	string	Terms and restrictions for extended use
total_sales*	integer	Total number of licenses sold for this listing
total_revenue_cents*	integer	Total revenue generated in cents
created_at*	string	ISO 8601 timestamp when the listing was created
updated_at*	string	ISO 8601 timestamp when the listing was last modified

▶ Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "string",
  "description": null,
  "is_active": true,
  "currency": "string",
  "price_personal_cents": null,
  "price_commercial_cents": null,
  "price_editorial_cents": null,
  "price_extended_cents": null,
  "license_terms_personal": null,
  "license_terms_commercial": null,
  "license_terms_editorial": null,
  "license_terms_extended": null,
  "total_sales": 0,
  "total_revenue_cents": 0,
  "created_at": "string",
  "updated_at": "string"
}

▶ Error Responses (3)

403Access denied

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

DELETE/v1/marketplace/listings/{listing_id}

Auth

Deactivate Listing

Deactivate a marketplace listing, removing it from sale.

▶View Details

Parameters

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

204: Listing deactivated

▶ Error Responses (3)

403Access denied

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

GET/v1/marketplace/sales

Auth

Get Seller Sales

List all sales (purchases by others) for your marketplace listings.

▶View Details

Parameters

Name	In	Type	Description
limit	query	integer	Maximum number of results to return
offset	query	integer	Number of results to skip for pagination

▶ Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "listing_id": "550e8400-e29b-41d4-a716-446655440000",
    "currency": "string",
    "price_cents": 0,
    "license_type": "string",
    "status": "string",
    "download_expires_at": null,
    "created_at": "string"
  }
]

▶ Error Responses (2)

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

GET/v1/marketplace/listings/{listing_id}/analytics/sales

Auth

Get Listing Sales Analytics

Get sales analytics for a marketplace listing.

▶View Details

Parameters

Name	In	Type	Description
listing_id*	path	string(uuid)	—
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 — Sales analytics returned

Field	Type	Description
total_sales*	integer	Total number of sales in the specified period
total_revenue_cents*	integer	Total revenue in cents in the specified period
daily_sales*	object[]	Daily breakdown of sales and revenue for chart visualization

▶ Example Response

{
  "total_sales": 0,
  "total_revenue_cents": 0,
  "daily_sales": [
    {
      "date": "string",
      "count": 0,
      "revenue_cents": 0
    }
  ]
}

▶ Error Responses (3)

400Invalid date format

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

POST/v1/marketplace/listings/{listing_id}/purchase

Auth

Initiate Purchase

Start a purchase for a photo listing via Stripe checkout.

▶View Details

Parameters

Name	In	Type	Description
listing_id*	path	string(uuid)	—
success_url	query	string	—
cancel_url	query	string	—

Request Body (application/json) *

Field	Type	Description
license_type*	"personal" \| "commercial" \| "editorial" \| "extended"	—

▶ Example Request

{
  "license_type": "commercial"
}

✓ Response 200 — Checkout session created

Field	Type	Description
purchase_id*	string	Purchase Id
checkout_url	string	Checkout Url

▶ Example Response

{
  "purchase_id": "string",
  "checkout_url": null
}

▶ Error Responses (3)

400Invalid price

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

GET/v1/marketplace/purchases

Auth

Get Buyer Purchases

List all photo licenses you have purchased.

▶View Details

Parameters

Name	In	Type	Description
limit	query	integer	Maximum number of results to return
offset	query	integer	Number of results to skip for pagination

▶ Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "listing_id": "550e8400-e29b-41d4-a716-446655440000",
    "currency": "string",
    "price_cents": 0,
    "license_type": "string",
    "status": "string",
    "download_expires_at": null,
    "created_at": "string"
  }
]

▶ Error Responses (2)

404Not found

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

GET/v1/marketplace/purchases/{purchase_id}/download

Auth

Download Purchased Image

Download the original high-resolution image for a completed purchase.

▶View Details

Parameters

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

▶ Example Response

null

▶ Error Responses (5)

402Payment pending

403Access denied

404Not found

410Download expired

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

GET/v1/marketplace/listings/{listing_id}/download

Auth

Download Listing Image

Download the original high-resolution image by listing ID.

▶View Details

Parameters

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

▶ Example Response

null

▶ Error Responses (4)

403Purchase required

404Not found

410Download expired

422Validation Error

{
  "detail": [
    {
      "loc": [
        "..."
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

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