Documentation

API Reference

RESTful API for product registration, verification, provenance tracking, and threat intelligence. All responses are JSON. Base URL: https://genuproof.com

POST/api/brands

Register a new brand

Request Body
{ "name": "Luxe Watches", "domain": "luxe.com", "industry": "fashion" }
Response
{ "id": "uuid", "name": "...", "plan": "free" }
POST/api/products/register

Register a single product with cryptographic certificate

Request Body
{ "brandId": "uuid", "name": "Chronograph 42mm", "sku": "LW-01", "category": "Watches", "manufacturingLocation": "Geneva" }
Response
{ "productId": "hex", "verificationCode": "abc123", "hash": "sha256...", "signature": "hmac..." }
POST/api/products/batch

Register up to 50 products in one request

Request Body
{ "brandId": "uuid", "products": [{ "name": "...", "sku": "..." }, ...] }
Response
{ "registered": 50, "products": [...] }
GET/api/products/verify?code=abc123

Verify a product by code. Records scan, runs anomaly detection.

Response
{ "authentic": true, "product": {...}, "events": [...], "certificate": { "signatureValid": true, "chainIntegrity": true } }
POST/api/products/events

Add a hash-chained provenance event

Request Body
{ "productId": "hex", "type": "shipped", "actor": "FedEx", "location": "NYC" }
Response
{ "hash": "sha256...", "previousHash": "sha256...", "timestamp": "..." }
POST/api/products/transfer

Transfer product ownership. Creates transfer event, updates status.

Request Body
{ "productId": "hex", "newOwner": "New Owner LLC", "location": "Miami, FL" }
Response
{ "success": true, "hash": "sha256...", "newOwner": "..." }
GET/api/threats?brandId=uuid

Fetch threat alerts for a brand

Response
{ "threats": [{ "type": "geographic_anomaly", "severity": "high", "details": "..." }] }
GET/api/products/list?brandId=uuid

List all products for a brand (via GSI1)

Response
{ "products": [...], "count": 42 }
GET/api/products/qr?code=abc123

Generate QR code (PNG or SVG) for a verification code

Response
Binary PNG or SVG image
POST/api/products/recall

Recall a product. Creates recall event, updates status to recalled, generates critical threat alert.

Request Body
{ "productId": "hex", "reason": "Safety defect in batch #42", "issuedBy": "Quality Assurance" }
Response
{ "success": true, "hash": "sha256...", "status": "recalled" }
GET/api/products/search?code=abc123

Search products by verification code, product ID, or brand ID

Response
{ "found": true, "product": { "productId": "...", "name": "...", "status": "active" } }
GET/api/products/certificate?code=abc123

Export full cryptographic certificate as JSON (product + crypto verification + provenance chain)

Response
{ "version": "1.0", "product": {...}, "cryptography": {...}, "provenance": {...}, "verification": {...} }
GET/api/brands/list

List all registered brands

Response
{ "brands": [{ "id": "...", "name": "...", "domain": "..." }], "count": 3 }
GET/api/brands/stats?brandId=uuid

Real-time brand statistics (products, scans, threats, status breakdown)

Response
{ "productCount": 42, "activeProducts": 40, "totalScans": 1250, "unresolvedThreats": 2 }
GET/api/audit?limit=30

Platform-wide audit log — events, scans, and alerts sorted by time

Response
{ "entries": [{ "type": "event", "action": "shipped", "actor": "FedEx", "timestamp": "..." }] }
GET/api/explore?limit=50

Public product gallery — all verified products for consumer browsing

Response
{ "products": [...], "count": 50 }
GET/api/health

Platform health check — API status, database connectivity, latency

Response
{ "status": "operational", "services": { "api": "healthy", "database": "healthy", "dbLatency": "8ms" } }
GET/api/og?brand=X&product=Y

Dynamic Open Graph image generation for social sharing

Response
1200x630 PNG image

Cryptographic Design

Product Hash: Each product record is canonicalized to JSON and hashed with SHA-256. The hash is then signed with HMAC-SHA256 using a server-side secret. Verification recomputes the hash and checks both the hash match and the HMAC signature.

Provenance Chain: Each supply chain event includes the hash of the previous event. The chain starts with a genesis event whose previousHash is SHA-256 of an empty string. Tampering with any event breaks all subsequent hash links.

Anomaly Detection:Every verification scan records the requester's IP and geolocation. The system checks for geographic anomalies (same product scanned from 3+ countries in 24 hours) and burst patterns (10+ scans per hour).