Provenance API Documentation

Version 1.0.0

Base URL: http://localhost:3003

Authentication

Bearer Token (JWT) — Include in header: Authorization: Bearer <token>

Token expiry: 7 days (configurable)

Authentication

POST /api/auth/register

Register a new user

Rate limit: 5 requests per 15 minutes

Request Body
email: string (required)
password: string (required, min 8 chars)
Response
success: boolean
user: { id, email, role }
token: string (JWT)
POST /api/auth/login

Login user

Rate limit: 5 requests per 15 minutes

Request Body
email: string (required)
password: string (required)
Response
success: boolean
user: object
token: string (JWT)
GET /api/auth/me

Get current user (requires auth)

Response
success: boolean
user: object

Content

POST /api/register

Register content for provenance tracking

Rate limit: 20 requests per hour

Request Body
file: File (multipart/form-data, max 50MB)
Response
success: boolean
contentHash: string
fingerprintHash: string
txHash: string
timestamp: string (ISO)
POST /api/verify

Verify content authenticity

Rate limit: 50 requests per hour

Request Body
file: File (multipart/form-data, max 50MB)
Response
success: boolean
contentHash: string
registered: boolean
verified: boolean (true only when content has completed verification state)
creator: string
creatorId: string
registeredAt: string (ISO)
timestamp: string (ISO, alias of registeredAt)
result: authentic | pending | not_found
POST /api/batch-verify

Verify multiple files at once

Rate limit: 20 requests per hour

Request Body
files: File[] (multipart/form-data, max 10 files)
Response
success: boolean
results: array of verification results
GET /api/status/:contentHash

Get content status by hash

Response
success: boolean
contentHash: string
registered: boolean
verified: boolean
creator: string
timestamp: string (ISO)

System

GET /health

Health check endpoint

Response
status: ok | error
timestamp: string (ISO)
uptime: number (seconds)
environment: string
version: string
GET /ready

Dependency-aware readiness endpoint

Response
status: ready | not_ready
checks: { startup, database, redis }
details: { database, redis }
timestamp: string (ISO)
GET /api/statistics

Get system statistics

Response
success: boolean
statistics: { totalRegistrations, totalVerifications, verifiedCount, pendingCount, notFoundCount }
GET /api/recent

Get recent registrations

Response
success: boolean
recent: array of recent registrations

Metadata

POST /api/metadata

Get content metadata

Request Body
file: File (multipart/form-data)
Response
success: boolean
metadata: { filename, size, mimetype, contentHash, fingerprintHash, dimensions }
POST /api/ipfs/upload

Upload content to IPFS

Request Body
file: File (multipart/form-data)
Response
success: boolean
cid: string (IPFS CID)
gatewayUrl: string
timestamp: string (ISO)

Rate Limits

General: 100 requests per 15 minutes
Authentication: 5 requests per 15 minutes
Upload: 20 requests per hour
Verification: 50 requests per hour

Error Codes

Code Description
400Bad Request — Invalid input
401Unauthorized — Invalid or missing token
403Forbidden — Insufficient permissions
404Not Found — Resource not found
409Conflict — Resource already exists
429Too Many Requests — Rate limit exceeded
500Internal Server Error
503Service Unavailable