API Overview

What the API Covers

The TimeProof API gives you programmatic access to the release-target V1 product model. You can automate timestamp creation, verify hashes, manage organizations, purchase packs, manage subscriptions, and retrieve certificates without opening the web interface.

The API is organized into logical groups:

Route Group	Base Path	Purpose
Auth	/api/auth	Wallet authentication via SIWE
Account	/api/account	Profile, unified balance, activity
Timestamps	/api/timestamps	Create and manage timestamp batches
Certificates	/api/certificates	Legal-Grade certificates
Verify	/api/verify	Public hash verification
Payments	/api/payments	One-time packs and Stripe checkout
Subscriptions	/api/subscriptions	Plan checkout, upgrades, and spending limits
Identity	/api/identity	Identity verification
Organizations	/api/organizations	Team management
Notifications	/api/notifications	In-app notification history
Settings	/api/settings	Notification preferences
Admin	/api/admin	Admin dashboard (restricted)
Config	/api/config	Frontend-readable operation costs

Authentication Model

TimeProof uses wallet-based authentication — no username, no password, no API key. The flow is:

1. Request a nonce — GET /api/auth/nonce returns a random challenge
2. Sign with your wallet — create a SIWE message containing the nonce, sign it with your private key
3. Submit the signature — POST /api/auth/verify validates the signature and sets an HTTP-only session cookie
4. Use the session — all subsequent requests include the session cookie automatically

This model is more secure than traditional API keys because your private key never leaves your wallet. The server verifies you own the wallet address by checking the cryptographic signature.

See API Authentication for the complete flow with code examples.

Request and Response Format

All API requests and responses use JSON:

Content-Type: application/json

Successful responses return the requested data directly:

{
  "user": { "id": 1, "walletAddress": "0x..." },
  "balance": 842
}

Error responses include a message describing the problem:

{
  "error": "Insufficient credits",
  "required": 2,
  "available": 0,
  "anchorMode": "instant"
}

HTTP status codes follow REST conventions:

Code	Meaning
200	Success
201	Created (new resource)
400	Bad request (invalid input)
401	Unauthorized (no session or expired)
403	Forbidden (insufficient permissions)
404	Not found
429	Rate limited
500	Server error

Public vs. Authenticated Endpoints

Most endpoints require authentication, but several critical ones are public:

Public (no auth required):

• GET /api/verify/check/:hash — verify any timestamp
• POST /api/verify — full verification with file
• POST /api/verify/merkle — independent Merkle proof verification
• GET /api/payments/packs — view available credit packs
• GET /.well-known/jwks.json — public key for JWS verification
• GET /health — server health check

Authenticated (session required):

• All timestamp creation and listing endpoints
• All certificate endpoints
• All organization management endpoints
• Account and settings endpoints
• Payment checkout endpoints

Working with the API

Using cURL

# Get a nonce
curl -c cookies.txt https://api.timeprooflabs.com/api/auth/nonce

# After signing, verify
curl -c cookies.txt -b cookies.txt \
  -X POST https://api.timeprooflabs.com/api/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"message": "...", "signature": "0x..."}'

# Create a timestamp
curl -b cookies.txt \
  -X POST https://api.timeprooflabs.com/api/timestamps \
  -H "Content-Type: application/json" \
  -d '{"files": [{"name": "doc.pdf", "hash": "sha256...", "size": 12345}], "anchorMode": "instant"}'

Health Check

Before integrating, verify the server is running:

GET /health

{
  "ok": true,
  "timestamp": "2026-02-03T12:00:00Z",
  "version": "1.0.0"
}

Integration Patterns

Batch Automation

For high-volume timestamping, use scheduled mode with batch jobs. Send multiple file hashes in a single API call, and they’ll be anchored together with a Merkle tree while drawing from the same unified balance.

Verification Webhooks

After creating a timestamp, poll the job status endpoint or use WebSocket notifications to know when anchoring is complete. The receipt endpoint provides all data needed for verification.

Organization Workflows

Create an organization, invite team members by wallet address, and assign roles (admin, member, viewer). All timestamps created under an organization are visible to its members.

Next Steps

• API Authentication — implement the SIWE sign-in flow
• API Timestamp Endpoints — create and retrieve timestamps
• API Verification Endpoints — verify hashes programmatically
• API Rate Limits — understand throttling and quotas