Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Truthlocks Content Protection lets individual creators prove authorship of their work with cryptographic attestations anchored to an immutable transparency log. This guide covers the full flow: signing up, protecting content, managing protections, sharing proofs, and embedding badges.

​
How it works

1

Sign up

Sign up at verify.truthlocks.com/signup. When you first visit the Protect page, a setup card prompts you to provision your signing identity with one click — a personal Ed25519 issuer and key pair are created automatically.
2

Upload content

On the Protect page, select a file up to 50 MB. Your file is hashed client-side (SHA-256) — the file itself never leaves your browser.
3

AI metadata

Metadata is automatically extracted (category, description, content type) to enrich your protection record.
4

Mint attestation

The hash and metadata are signed by your personal issuer and anchored to the transparency log.
5

Share proof

Share via a public proof page, embeddable badge, or downloadable certificate.

​
Protecting Content via the API

Compute the SHA-256 hash of your content client-side, then call the mint endpoint:
Request
POST /v1/consumer/mint
Authorization: Bearer <token>
Content-Type: application/json

{
  "content_hash": "e3b0c44298fc1c149afbf4c8...",
  "title": "My Photograph",
  "description": "Sunset photo taken in Big Sur",
  "file_name": "sunset.jpg",
  "file_size": 4521984,
  "content_type": "image",
  "category": "photography",
  "visibility": "public"
}
The response includes your attestation ID, the content_hash you submitted, the protected_at timestamp, and a shareable proof URL:
Response
{
  "protection_id": "a1b2c3d4-...",
  "attestation_id": "b2c3d4e5-...",
  "content_hash": "e3b0c44298fc1c149afbf4c8...",
  "protected_at": "2026-03-25T22:17:01Z",
  "verify_url": "https://verify.truthlocks.com/proof/b2c3d4e5-...",
  "share_url": "https://verify.truthlocks.com/proof/b2c3d4e5-..."
}
Use content_hash and protected_at to confirm which content was protected and exactly when, without making a follow-up API call.

​
Client-side hashing (JavaScript)

The file never leaves your browser. Compute the hash before calling the API: 
async function hashFile(file) {
  const buffer = await file.arrayBuffer();
  const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
}

const hash = await hashFile(selectedFile);
// Pass 'hash' as content_hash to POST /v1/consumer/mint

​
Duplicate and similarity detection

Before minting a protection, Truthlocks checks whether similar content has already been protected. After hashing your file, the platform runs a similarity check and returns any matches above a confidence threshold. Each match includes:
  • Similarity score — how closely the content matches an existing protection.
  • Owner — the username of the person who protected the original.
  • Date — when the original protection was created.
If similar content is found, you can review the matches and decide whether to proceed. This helps prevent accidental duplicates and surfaces potential conflicts early.
Similarity detection runs automatically in the Protect page UI. When using the API directly, you can check for duplicates before minting by calling POST /v1/consumer/similarity with your content hash.

​
Quick Protect

Quick Protect is a streamlined flow that lets you protect content in a single step from the consumer dashboard. Instead of navigating to the Protect page, selecting a file, reviewing metadata, and confirming — Quick Protect combines these into one action. From your dashboard, drag a file onto the Quick Protect drop zone — or click it to open a file picker. The protection is minted immediately: Truthlocks hashes the file client-side, runs AI metadata extraction in the background, and creates the protection. The result appears in your protections list within seconds.
Quick Protect always creates private protections. To make a protection public and add it to your portfolio, toggle its visibility from the Protections page.
Quick Protect uses the same SHA-256 client-side hashing and AI metadata extraction as the full Protect page. The only difference is the simplified UI — your file never leaves your browser.

​
Signing identity auto-provisioning

The first time you protect content, Truthlocks creates a personal signing identity (issuer and Ed25519 key pair) for your account automatically. This is a one-time setup:
  1. You submit a protection request.
  2. If no signing identity exists, the platform provisions one.
  3. The protection is then minted using your new identity.
In the Protect page UI, you see a brief setup prompt during this step. Subsequent protections proceed without interruption. If you are using the API and receive an HTTP 412 response with a NO_ISSUER error code, call POST /v1/consumer/me/provision-issuer to create your signing identity, then retry the mint request.

​
AI metadata extraction

When you upload a file through the Protect page, Truthlocks automatically extracts metadata to enrich your protection record:
  • Title and description — generated from the file content.
  • Category — one of: photography, digital_art, source_code, document, music, video, design, data, or other.
  • Content type — the detected media type of the file.
For image files (JPEG, PNG), EXIF metadata such as camera model, GPS coordinates, and capture date is also extracted when available. For text-based files (source code, markdown, configuration files), a preview of the first 4 KB is used for classification. You can edit the auto-generated title, description, and visibility before confirming the protection.

​
Verifying a file

Anyone can verify that a file has not been altered since it was protected. Truthlocks compares the SHA-256 hash of the file you provide against the hash that was stored when the content was originally protected.

​
Verify through the portal

The verify portal lets you check a file without writing any code:
1

Open the verify portal

Go to verify.truthlocks.com and switch to the File tab.
2

Enter the attestation ID

Paste the attestation ID of the protection you want to verify.
3

Select your file

Choose the file you want to check. The SHA-256 hash is computed entirely in your browser — the file is never uploaded.
4

Read the result

The portal displays one of three outcomes:
  • Document Verified — the file matches the original protection.
  • Document Altered — the file has been modified since it was protected. The portal shows both the uploaded and expected hashes.
  • Document Hash Not Available — the protection was created before document hashes were stored, so the check cannot be performed.
Portal verifications are free and unlimited. No account or API key is required.

​
Verify through the API

Pass the file’s SHA-256 hash as document_hash_hex to the Verify endpoint: 
curl -X POST https://api.truthlocks.com/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "attestation_id": "b2c3d4e5-...",
    "document_hash_hex": "e3b0c44298fc1c149afbf4c8..."
  }'
If the hashes match, the verdict is VALID. If they differ, the verdict is ALTERED. See the Verify API reference for the full list of verdicts and reason codes.
Always compute the hash from the original file, not from the base64url-encoded payload. This ensures the hash matches what was stored at mint time.

​
How the document hash is stored

When you protect content, Truthlocks stores a SHA-256 hash that verifiers use to confirm the original file has not been altered. In the consumer flow, this is the content_hash you compute client-side. In the B2B/API flow, you can pass the hash explicitly using the document_hash parameter on the Mint Attestation endpoint.
All existing consumer protections now include a verifiable document_hash in their proof bundles, so file integrity verification works for both new and older records.

​
Managing protections

  • List protections: GET /v1/consumer/protections returns all your protected content.
  • Toggle visibility: PUT /v1/consumer/protections/{id}/visibility with {"visibility": "public"} or "private".
  • Set username: PUT /v1/consumer/me/username to claim a public portfolio URL.
  • View stats: GET /v1/consumer/stats for total protections, public count, and verification count.

​
Public proof pages

Every protection generates a public proof page at the verify_url returned by the mint endpoint. Anyone can view the proof page without logging in — it shows what was protected, when, and by whom. Each proof page includes an AI-generated summary describing the protected content, its category, and the protection date. Summaries are cached for five minutes and regenerate on the next visit after expiry. If AI is unavailable, a structured template summary is shown instead. See the AI metadata guide for details on how summaries and caching work. To programmatically fetch proof page data (for example, to render custom proof pages or generate Open Graph link previews), use the Get Proof Page Metadata endpoint: 
curl https://api.truthlocks.com/v1/public/proof/{attestation_id}
This is a public endpoint — no API key or authentication is required. The response includes the title, description, content type, file metadata, content hash, and protection timestamp.
The proof metadata endpoint is read-only and returns only the metadata you provided when protecting the content. Your original file is never stored or exposed.

​
Embeddable Badges

Add a verification badge to your website, README, or portfolio: 
[![Protected by Truthlocks](https://verify.truthlocks.com/badge/ATTESTATION_ID)](https://verify.truthlocks.com/proof/ATTESTATION_ID)
The badge dynamically shows “Verified” or “Unverified” status and is cached for 10 minutes.

​
Downloadable Certificates

Download a formal SVG protection certificate for any attestation: 
GET /api/certificate/ATTESTATION_ID         → SVG download
GET /api/certificate/ATTESTATION_ID?format=html  → HTML view
Certificates include the title, category, attestation ID, content hash, date, and a verified seal. Use them for legal evidence, portfolio displays, or print.

​
Public Portfolio

Set a username to get a public portfolio page at verify.truthlocks.com/portfolio/YOUR_USERNAME. Only protections with visibility: "public" are shown. The portfolio includes OpenGraph metadata for rich social sharing.

​
Pricing Tiers

  • Free: 50 protections/month, SHA-256 hashing, transparency log, shareable links, public portfolio.
  • Creator ($9/mo): 500 protections/month, priority processing, custom badges, advanced analytics, API access.
  • Pro ($29/mo): Unlimited protections, bulk API, custom certificates, priority support, team collaboration.

​
First-time setup

New users see a Set up content protection card on their dashboard. Click the setup button to provision your personal signing identity — this creates an Ed25519 issuer and key pair in one click. After provisioning, you are redirected to the Protect page to start protecting content.
You only need to do this once. After your signing identity is provisioned, the setup card disappears and you can protect content directly.

​
Security model

  • Files never leave the browser — only the SHA-256 hash is transmitted.
  • Each consumer gets a personal Ed25519 signing key provisioned automatically on first use.
  • Maximum file size is 50 MB.
  • Attestations are anchored to an append-only transparency log (RFC 6962 compatible).
  • Row Level Security isolates all tenant data in PostgreSQL.
  • Proofs are independently verifiable without Truthlocks involvement.