API Docs — TimeProofs

Start · Quickstart

Quickstart (v0.2)

Flow: (1) compute SHA-256 locally → (2) POST /api/timestamp → (3) save the .tproof.json proof → (4) verify later with /api/verify using the proof.

# 1) Hash locally (example)
# sha256sum myfile.bin | awk '{print $1}'

# 2) Timestamp: server signs the hash and returns a proof
curl -sS https://api.timeproofs.io/api/timestamp \
  -H "Content-Type: application/json" \
  -d '{
    "hash":"<sha256-hex>",
    "type":"document",
    "meta":{"source":"cli"}
  }' | tee proof.tproof.json

# 3) Verify later (proof-based)
# Option A (recommended): requires jq
jq -c '{bundle:.}' proof.tproof.json | \
curl -sS https://api.timeproofs.io/api/verify \
  -H "Content-Type: application/json" \
  -d @-

# Option B (no jq): paste the proof JSON into "bundle" manually
# curl -sS https://api.timeproofs.io/api/verify -H "Content-Type: application/json" -d '{"bundle":{...}}'

Reference · Endpoints

Endpoints

Base URL: https://api.timeproofs.io/api

POST /timestamp

Create a signed proof from a SHA-256 hash (no original upload).

POST /verify

Verify a proof’s cryptographic integrity (stateless; proof required).

GET /health

Health check (service availability).

POST /timestamp

POST https://api.timeproofs.io/api/timestamp
Content-Type: application/json
Accept: application/json

{
  "hash": "64-hex-sha256",
  "type": "document",
  "meta": { "source": "web" }
}

POST /verify

POST https://api.timeproofs.io/api/verify
Content-Type: application/json
Accept: application/json

{
  "bundle": { ...the .tproof.json content... }
}

Format · Proof file

Proof file (.tproof.json)

A proof contains only hash + timestamp + signature (and optional meta). Your original content is never stored.

{
  "version": "timeproofs-0.2",
  "hash": {
    "algorithm": "SHA-256",
    "value": "sha256-hex"
  },
  "timestamp": {
    "issuedAt": "2025-11-04T10:22:33.123Z",
    "issuer": "https://api.timeproofs.io",
    "nonce": "hex-128bit"
  },
  "proof": {
    "algo": "Ed25519",
    "signature": "hex-signature",
    "keyId": "tp-v0-2-main"
  },
  "meta": {
    "type": "document",
    "source": "web:docs"
  }
}

Ops · Errors

Errors

Clients should treat errors as HTTP status + a human message. Do not hardcode undocumented error codes.

400 Bad Request

Invalid input (e.g., missing fields, malformed JSON, hash not 64-hex).

413 Payload Too Large

Request exceeds limits (client should reduce payload).

429 Too Many Requests

Rate limited: exponential backoff + jitter (client responsibility).

5xx Server Error

Temporary failure: retry with backoff and surface a clear message.

Typical error payload (example)

{
  "error": "bad_request",
  "message": "Hash must be 64 hex characters."
}

Your integration should always handle: non-JSON responses, missing fields, and unexpected shapes.

Offline · What “offline” means

Offline

“Offline” means you can keep, move, inspect, and archive the proof file locally anytime. A proof is self-contained: it carries the hash, timestamp, and signature.

For cryptographic validation, you need a verifier that knows TimeProofs public keys: you can use the TimeProofs API (/api/verify) when online, or any ProofSpec-compatible verifier that supports the same keys.

Practical workflow: store .tproof.json next to the original file, keep both immutable, and re-verify after transfers/pipelines.

Help · FAQ

FAQ

Do you store my content?
No. Your original file stays with you. Proofs are hash-only.

Why is v0.2 “stateless”?
Verification uses the proof file, not a database lookup.

Is a file date enough?
No. File dates are local and editable. TimeProofs signs a cryptographic fingerprint at a precise time.

Is this notarization / legal certification?
No. TimeProofs provides a technical proof of existence and integrity, not a legal qualification.

↑ Top